# Prom.ua API — search Ukraine's multi-seller marketplace and read full products: price, old price, wholesale tiers, availability, seller with rating, city and phone, delivery and payment options, attributes, product and seller reviews, seller catalogues and categories

> Search prom.ua by keyword (Ukrainian, Russian or Latin) and/or category with the site's own filters: price range, in stock, discounted, wholesale, pay in parts, Prom-payment, free Smart delivery, delivery method, seller city/region, 4+ star reviews, condition, brand, one seller, and 4 sort orders. Each row is one seller's offer: price as printed, old price, wholesale tiers, availability, rating and review count, the seller (name, city, positive-review % and count) and the model group the same item belongs to across sellers. Needs `query` or `category`.
> ReefAPI engine `prom-ua` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/prom-ua/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/prom-ua/v1/search — 2 credits
Search prom.ua by keyword (Ukrainian, Russian or Latin) and/or category with the site's own filters: price range, in stock, discounted, wholesale, pay in parts, Prom-payment, free Smart delivery, delivery method, seller city/region, 4+ star reviews, condition, brand, one seller, and 4 sort orders. Each row is one seller's offer: price as printed, old price, wholesale tiers, availability, rating and review count, the seller (name, city, positive-review % and count) and the model group the same item belongs to across sellers. Needs `query` or `category`.

**Parameters:**
- `query` (string, optional) — Search words, e.g. 'iphone 15', 'кавоварка', 'шини 205/55 r16'. Needs query OR category.
- `category` (string, optional) — Prom.ua category id (`category_id` of any row, or the `categories` action). With query it narrows the search; alone it browses the category. An id prom.ua does not know is rejected.
- `seller_id` (string, optional) — Only this seller's offers (needs `query`; to list a seller's whole catalogue use the `seller` action).
- `min_price` (number, optional) — Lowest price in UAH (applies to the price the page prints).
- `max_price` (number, optional) — Highest price in UAH.
- `in_stock` (boolean, optional) — Only items marked 'В наявності' (in stock).
- `discounted` (boolean, optional) — Only items with a discount (old price struck through).
- `wholesale` (boolean, optional) — Only items that have wholesale (опт) price tiers.
- `pay_in_parts` (boolean, optional) — Only items payable in instalments ('Оплатити частинами').
- `prom_payment` (boolean, optional) — Only items with Prom-payment (paid on prom.ua with buyer protection).
- `free_delivery_smart` (boolean, optional) — Only items with free delivery for Smart subscribers.
- `delivery` (enum, optional) — Only sellers offering this delivery method. [one of: nova_poshta, ukrposhta, rozetka_delivery, pickup, meest_express, delivery_auto]
- `region` (string, optional) — Only items the seller ships from this city/region (product `ships_from`, which can differ from the seller's own city): prom.ua's region slug (kyiv, lviv, odessa, kharkov, dp = Dnipro, ...). An unknown slug is rejected.
- `rating_4_plus` (boolean, optional) — Only items rated 4 stars or more. prom.ua applies it to the model rating (all sellers' reviews of the same item, `model.rating`), not only this offer's own.
- `with_review_media` (boolean, optional) — Only items with photo/video buyer reviews.
- `condition` (enum, optional) — Item condition (prom.ua's 'Стан' attribute). [one of: new, used, refurbished, markdown]
- `brand_id` (string, optional) — Brand id (`brand_id` in rows, e.g. 80130 = IPhone as sellers spell it).
- `sort` (enum, optional, default "relevance") — Result order (prom.ua's own sort bar). With a price sort prom.ua puts the strong matches first and the looser ones after them (`weak_match: true`). [one of: relevance, popularity, price_asc, price_desc]
- `page_size` (integer, optional, default 48) — Rows per call (default 48, at most 60).
- `offset` (integer, optional, default 0) — Rows to skip. prom.ua serves at most ~9 000 results per query; offsets above 8900 are refused.
- `page` (integer, optional) — Convenience: offset = (page-1) x page_size. Ignored when offset is given.
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** results[]{product_id, name, url, image, sku, price (the price printed in bold), price_old (struck through), discount_pct, price_is_from ('від'), price_on_request, price_note, currency (UAH), price_usd_source, unit, wholesale_prices[]{price, min_quantity}, selling_type (retail / wholesale / universal), discount_ends, pay_in_parts_monthly, availability (avail / order / not_avail / waiting), availability_text, in_stock, ready_to_ship, stock_ending, available_from, rating, review_count, brand, brand_id, category_id, category_ids[], seller{seller_id, name, url, city, country, positive_pct, review_count, top_seller, return_days, non_returnable}, model{model_id, rating, review_count, offers_count, sellers_count, min_price, max_price, offer_ids[]} (same item from other sellers; rating = reviews of the model across sellers), prosale, weak_match, is_adult} + total, total_is_approximate, offset, next_offset, has_more, corrected_query, query_expansion (when prom.ua widened the words), category, region

**Example request body:**
```json
{
  "query": "кавоварка рожкова",
  "in_stock": true
}
```

### POST https://api.reefapi.com/prom-ua/v1/product — 1 credit
Full prom.ua product by product_id or URL: name, description, images, video, brand, GTIN/MPN when the seller filled them, price as printed, old price, discount, 'from' price, wholesale tiers with minimum quantities, minimum order, instalment price, availability, rating and review count, every attribute, category path, warranty, the seller (name, city, phone, website, years on prom.ua, positive-review %, orders delivered, return terms), delivery options with their prices and payment options, the model group across sellers (offer count, seller count, min/max price) and the item's variations.

**Parameters:**
- `product_id` (string, optional) — Prom.ua product id: the number after `/p` in a product URL (`prom.ua/ua/p3026527730-....html`), returned as `product_id` in every search row. Provide product_id OR url.
- `url` (string, optional) — A prom.ua product URL; alternative to product_id.
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** item{product_id, name, url, sku, gtin, mpn, brand, brand_id, price, price_old, discount_pct, price_is_from, price_on_request, price_note, currency, price_usd_source, unit, wholesale_prices[], selling_type, discount_ends, pay_in_parts_monthly, min_order_quantity, min_order_sum, availability, availability_text, in_stock, ready_to_ship, stock_ending, available_from, listed, rating, review_count, orders_count, description, images[], videos[], category{category_id, name, url}, category_ids[], breadcrumbs[]{name, url}, attributes[]{group, name, value, attribute_id}, warranty_months, seller{seller_id, name, url, city, phone, website, years_on_prom, is_operating, last_active, orders_delivered, logo, positive_pct, review_count, top_seller, return_days, non_returnable}, ships_from[], delivery_options[]{type, name, note, via_prom_shipping, free_via_prom_shipping}, payment_options[]{type, name, note}, model{model_id, name, rating, review_count, offers_count, sellers_count, min_price, max_price}, variations[]{product_id, url, attributes{}, availability, ready_to_ship}, is_adult}

**Example request body:**
```json
{
  "url": "https://prom.ua/ua/p3026527730-smartfon-apple-iphone.html"
}
```

### POST https://api.reefapi.com/prom-ua/v1/reviews — 1 credit
Buyer reviews of a prom.ua product: star rating, title, text, pros, cons, date, author as prom.ua shows it, verified-purchase flag, likes, photos, video, the seller it was bought from and the comment thread (seller replies flagged), plus the product's total review count and star distribution.

**Parameters:**
- `product_id` (string, required) — Prom.ua product id.
- `sort` (enum, optional, default "most_useful") — Review order (prom.ua's own options). [one of: most_useful, newest, highest_rating, lowest_rating]
- `sentiment` (enum, optional) — prom.ua's own split: positive = 4-5 stars, negative = 1-3 stars (measured: 9 positive + 1 three-star negative on a 10-review item). [one of: positive, negative]
- `with_media` (boolean, optional) — Only reviews with photos or video.
- `verified_only` (boolean, optional) — Only reviews from buyers who purchased on prom.ua.
- `page` (integer, optional, default 1) — Review page.
- `page_size` (integer, optional, default 10) — Reviews per page (at most 50).
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** reviews[]{review_id, product_id, rating, title, text, pros, cons, date, author, verified_purchase, purchase_note, likes, dislikes, photos[], video, seller_id, seller_name, comments[]{date, author, from_seller, text}, url} + total, stars{1..5}, product_name, page, page_size, has_more, sort, sentiment

**Example request body:**
```json
{
  "product_id": "2011334336"
}
```

### POST https://api.reefapi.com/prom-ua/v1/seller — 2 credits
A prom.ua seller (shop) profile and its product catalogue: name, phone, website, city, years on prom.ua, last activity, orders delivered, positive-review %, review counts and star distribution, the review tags buyers chose (fast dispatch, polite seller...), legal name and registry code when the seller published them, opening hours, return policy, and one page of its products with the same filters and rows as search.

**Parameters:**
- `seller_id` (string, required) — Prom.ua seller id (`seller.seller_id` in any row) or a seller URL (`prom.ua/ua/c3805778-boo-svit.html`).
- `min_price` (number, optional) — Lowest price in UAH (applies to the price the page prints).
- `max_price` (number, optional) — Highest price in UAH.
- `in_stock` (boolean, optional) — Only items marked 'В наявності' (in stock).
- `discounted` (boolean, optional) — Only items with a discount (old price struck through).
- `wholesale` (boolean, optional) — Only items that have wholesale (опт) price tiers.
- `pay_in_parts` (boolean, optional) — Only items payable in instalments ('Оплатити частинами').
- `prom_payment` (boolean, optional) — Only items with Prom-payment (paid on prom.ua with buyer protection).
- `free_delivery_smart` (boolean, optional) — Only items with free delivery for Smart subscribers.
- `delivery` (enum, optional) — Only sellers offering this delivery method. [one of: nova_poshta, ukrposhta, rozetka_delivery, pickup, meest_express, delivery_auto]
- `rating_4_plus` (boolean, optional) — Only items rated 4 stars or more. prom.ua applies it to the model rating (all sellers' reviews of the same item, `model.rating`), not only this offer's own.
- `with_review_media` (boolean, optional) — Only items with photo/video buyer reviews.
- `condition` (enum, optional) — Item condition (prom.ua's 'Стан' attribute). [one of: new, used, refurbished, markdown]
- `brand_id` (string, optional) — Brand id (`brand_id` in rows, e.g. 80130 = IPhone as sellers spell it).
- `sort` (enum, optional, default "relevance") — Result order (prom.ua's own sort bar). With a price sort prom.ua puts the strong matches first and the looser ones after them (`weak_match: true`). [one of: relevance, popularity, price_asc, price_desc]
- `page_size` (integer, optional, default 48) — Rows per call (default 48, at most 60).
- `offset` (integer, optional, default 0) — Rows to skip. prom.ua serves at most ~9 000 results per query; offsets above 8900 are refused.
- `page` (integer, optional) — Convenience: offset = (page-1) x page_size. Ignored when offset is given.
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** seller{seller_id, name, url, phone, website, logo, city, years_on_prom, registered_on_prom, is_operating, last_active, orders_delivered, positive_pct, review_count, reviews_in_rating, review_count_incl_product_reviews, rating_counters{}, review_tags[]{tag, type, count, percent}, legal{legal_name, edrpou_or_code, registration_number, legal_address}, schedule[], description, warranty_info, top_seller, return_days, non_returnable, reviews_url} + results[]{product_id, name, url, image, sku, price (the price printed in bold), price_old (struck through), discount_pct, price_is_from ('від'), price_on_request, price_note, currency (UAH), price_usd_source, unit, wholesale_prices[]{price, min_quantity}, selling_type (retail / wholesale / universal), discount_ends, pay_in_parts_monthly, availability (avail / order / not_avail / waiting), availability_text, in_stock, ready_to_ship, stock_ending, available_from, rating, review_count, brand, brand_id, category_id, category_ids[], seller{seller_id, name, url, city, country, positive_pct, review_count, top_seller, return_days, non_returnable}, model{model_id, rating, review_count, offers_count, sellers_count, min_price, max_price, offer_ids[]} (same item from other sellers; rating = reviews of the model across sellers), prosale, weak_match, is_adult} + total, offset, next_offset, has_more

**Example request body:**
```json
{
  "seller_id": "2916770"
}
```

### POST https://api.reefapi.com/prom-ua/v1/seller_reviews — 1 credit
Reviews of a prom.ua seller (shop): rating, text, date, author, the tags the buyer ticked, the products ordered, photos, the seller's public response and comments.

**Parameters:**
- `seller_id` (string, required) — Prom.ua seller id.
- `sort` (enum, optional, default "newest") — Review order (prom.ua's own options). [one of: newest, highest_rating, lowest_rating, most_liked, most_commented]
- `sentiment` (enum, optional) — Only positive or only negative reviews (prom.ua's own split). [one of: positive, negative]
- `with_text_only` (boolean, optional) — Only reviews with written text.
- `page` (integer, optional, default 1) — Review page.
- `page_size` (integer, optional, default 10) — Reviews per page (at most 50).
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** reviews[]{review_id, rating, text, date, author, tags[], ordered_products[]{product_id, name}, photos[], seller_response{text, date}, comments[], likes, dislikes} + seller_id, seller_name, positive_pct, review_count, page, page_size, has_more

**Example request body:**
```json
{
  "seller_id": "2916770"
}
```

### POST https://api.reefapi.com/prom-ua/v1/categories — 1 credit
Prom.ua category tree: without category_id the top-level departments; with it that category's name, alias, URL, its path from the root and its direct sub-categories. Ids work as `category` in search.

**Parameters:**
- `category_id` (string, optional) — Category id; omit for the top-level departments.
- `lang` (enum, optional, default "uk") — Language of names, attribute labels and availability text: Ukrainian (default) or Russian. Prices and ids do not change. [one of: uk, ru]

**Returns:** category{category_id, name, alias, url, is_leaf, path[]{category_id, name}} (with category_id) + categories[]{category_id, name, alias, is_leaf}

**Example request body:**
```json
{
  "category_id": "50902"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=prom-ua
- Human docs page: https://reefapi.com/docs/prom-ua
- Overview page: https://reefapi.com/prom-ua-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt