# Worten API — search worten.pt and Worten Canarias and read products with price, PVPR / promotion price, every marketplace seller's offer, stock, delivery and store pickup, EAN, specifications and Bazaarvoice reviews

> Search Worten (worten.pt or Worten Canarias) by keyword and/or category with the site's own filters: brand, price range, in stock online, on sale, seller (Worten itself, premium marketplace sellers, or one marketplace seller), condition (new / refurbished / outlet, worten.pt), 5 sort orders. Each row: product id, Worten reference (sku), EAN, name, brand, price, original price and its type (recommended retail price vs promotion), discount, stock, the featured offer's seller (Worten or marketplace), number of offers and the next offer's price, delivery price and days, rating and count, promotion window, energy class. Plus the source's total and its facets (category tree with ids, brands, sellers, condition, ratings, delivery time, price range).
> ReefAPI engine `worten` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/worten/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/worten/v1/search — 2 credits
Search Worten (worten.pt or Worten Canarias) by keyword and/or category with the site's own filters: brand, price range, in stock online, on sale, seller (Worten itself, premium marketplace sellers, or one marketplace seller), condition (new / refurbished / outlet, worten.pt), 5 sort orders. Each row: product id, Worten reference (sku), EAN, name, brand, price, original price and its type (recommended retail price vs promotion), discount, stock, the featured offer's seller (Worten or marketplace), number of offers and the next offer's price, delivery price and days, rating and count, promotion window, energy class. Plus the source's total and its facets (category tree with ids, brands, sellers, condition, ratings, delivery time, price range).

**Parameters:**
- `query` (string, optional) — Search words as typed into the Worten search box. Either `query` or `category_id` (or both) is required.
- `site` (enum, optional, default "pt") — Which Worten store: pt = worten.pt (Portugal), canarias = canarias.worten.es (Worten Canarias, Spain). Prices follow the store's own price list. worten.es (mainland Spain) no longer sells online and is refused. [one of: pt, canarias]
- `category_id` (string, optional) — Worten category id (26-character id, with or without the CMS- prefix) from facets.categories or a row's category_ids. Without `query` this lists the category.
- `category_level` (integer, optional) — Depth of `category_id` in the category tree (facets.categories report it). Optional: when omitted the engine tries levels 1-4 and stops at the first that has rows (one source call per level).
- `brand` (string, optional) — Brand as the facets list it (case-insensitive, e.g. APPLE, SAMSUNG). A brand the store does not carry returns 0 rows.
- `min_price` (number, optional) — Lowest price in EUR. Portuguese writing is accepted: 1.299,99
- `max_price` (number, optional) — Highest price in EUR.
- `in_stock` (boolean, optional) — Only products available online now.
- `on_sale` (boolean, optional) — Only products the site marks as on sale.
- `seller` (string, optional) — worten = sold by Worten itself; premium = the site's premium marketplace sellers; or one marketplace seller's facet value (e.g. cantinho-19663) from facets.other[key=seller_id]. [one of: worten, premium]
- `condition` (enum, optional) — worten.pt only: new, refurbished or outlet. [one of: new, refurbished, outlet]
- `sort` (enum, optional, default "relevance") — Result order. Note: a sorted listing can report a smaller total than relevance (rows without a value for the sort key drop out). [one of: relevance, price_asc, price_desc, rating, discount]
- `page` (integer, optional, default 1) — Result page. The source serves the first 1,000 rows of any search: page × page_size must be ≤ 1000 (page 41 at 24 rows, 20 at 48, 83 at 12).
- `page_size` (enum, optional, default "24") — Rows per page. [one of: 12, 24, 48]

**Returns:** results[]{product_id, sku, ean, eans, entity_id, webitem_id, name, brand, url, image, price, original_price, price_type (regular|recommended_retail_price|promotion), discount_pct, currency, in_stock, offer_id, seller{seller_id, name, is_worten, premium, rating, rating_count}, offer_count, second_offer_price, shipping{price, min_days, max_days}, free_delivery_list, rating, rating_count, variant_count, promo_start, promo_end, energy_class, release_date, badges[], tags[], category_ids[]} + total, page, page_size, last_page, has_more, site, facets{categories[]{category_id, label, count, level, children[]}, price_range, other[]{key, label, type, options[]}}

**Example request body:**
```json
{
  "query": "iphone",
  "brand": "APPLE"
}
```

### POST https://api.reefapi.com/worten/v1/product — 3 credits
Full Worten product record: name, brand, model, Worten reference, EAN, description, category, rating and count, the featured offer's price, original price and its type, discount, stock, seller (Worten or marketplace) and delivery / store-pickup options, EVERY seller's offer with its own price, stock, delivery days and cost, the cheapest in-stock offer, warranty and insurance add-ons with prices, energy class, release date, manufacturer, grouped technical specifications and the raw attribute list.

**Parameters:**
- `product_id` (string, optional) — Product id exactly as a search row returns it (product_id, a uuid). A Worten product URL (ending in the 7-digit reference) is accepted too. Give this, `sku` or `ean`.
- `sku` (string, optional) — Worten's product reference exactly as a search row returns it: 5-9 digits (the 'Referência' on the page), or MRKEAN-<ean> for products only marketplace sellers offer.
- `ean` (string, optional) — Barcode (EAN/GTIN, 8-14 digits) as a search row returns it.
- `site` (enum, optional, default "pt") — Which Worten store: pt = worten.pt (Portugal), canarias = canarias.worten.es (Worten Canarias, Spain). Prices follow the store's own price list. worten.es (mainland Spain) no longer sells online and is refused. [one of: pt, canarias]

**Returns:** {product_id, site, sku, ean, eans, entity_id, webitem_id, name, brand, model, type, url, image, description, rating, rating_count, category{category_id, name, url}, category_ids[], price, original_price, original_price_type, discount_pct, currency, in_stock, seller{...}, seller_type (worten|marketplace), fulfilment[]{type, label, min_days, max_days, free, price, note}, offer_count, cheapest_offer{offer_id, price, seller, seller_type}, offers[]{offer_id, is_featured_offer, seller{seller_id, name, is_worten, premium, rating, rating_count, orders}, seller_type, price, original_price, original_price_type, discount_pct, source_discount_pct, currency, in_stock, fulfilment[], pickup_in_store, tags[], seller_note, source_offer_code}, services[]{group, title, sku, name, price}, energy_class, release_date, manufacturer, badges[], variant_count, specifications[]{group, name, value}, properties{}}

**Example request body:**
```json
{
  "sku": "7851120"
}
```

### POST https://api.reefapi.com/worten/v1/offers — 2 credits
Every offer for one Worten product in one call — Worten's own and each marketplace seller's: price, original price, discount, stock, seller name / rating / order count, delivery days and cost, store pickup — plus the cheapest in-stock offer. Lighter than `product` for price monitoring.

**Parameters:**
- `product_id` (string, optional) — Product id exactly as a search row returns it (product_id, a uuid). A Worten product URL (ending in the 7-digit reference) is accepted too. Give this, `sku` or `ean`.
- `sku` (string, optional) — Worten's product reference exactly as a search row returns it: 5-9 digits (the 'Referência' on the page), or MRKEAN-<ean> for products only marketplace sellers offer.
- `ean` (string, optional) — Barcode (EAN/GTIN, 8-14 digits) as a search row returns it.
- `site` (enum, optional, default "pt") — Which Worten store: pt = worten.pt (Portugal), canarias = canarias.worten.es (Worten Canarias, Spain). Prices follow the store's own price list. worten.es (mainland Spain) no longer sells online and is refused. [one of: pt, canarias]

**Returns:** offers[]{offer_id, seller{...}, seller_type, price, original_price, original_price_type, discount_pct, source_discount_pct, currency, in_stock, fulfilment[], pickup_in_store, tags[], seller_note, source_offer_code} + product_id, sku, ean, name, offer_count, cheapest_offer

**Example request body:**
```json
{
  "sku": "8591075"
}
```

### POST https://api.reefapi.com/worten/v1/reviews — 2 credits
Written buyer reviews of a Worten product (the site's Bazaarvoice reviews): stars, title, text, date, nickname, verified-purchaser flag, recommended flag, helpful votes, sub-ratings, photos, brand responses. Plus the rating summary: average, distribution, total submissions and how many are ratings without text. Reviews are shared across a product's variants, as on the site.

**Parameters:**
- `entity_id` (string, optional) — The product's entity_id as a search row or product returns it (digits). Fastest form. `product_id`, `sku` or `ean` also work (one extra lookup).
- `product_id` (string, optional) — Product id exactly as a search row returns it (product_id, a uuid). A Worten product URL (ending in the 7-digit reference) is accepted too. Give this, `sku` or `ean`.
- `sku` (string, optional) — Worten's product reference exactly as a search row returns it: 5-9 digits (the 'Referência' on the page), or MRKEAN-<ean> for products only marketplace sellers offer.
- `ean` (string, optional) — Barcode (EAN/GTIN, 8-14 digits) as a search row returns it.
- `site` (enum, optional, default "pt") — Which Worten store: pt = worten.pt (Portugal), canarias = canarias.worten.es (Worten Canarias, Spain). Prices follow the store's own price list. worten.es (mainland Spain) no longer sells online and is refused. [one of: pt, canarias]
- `sort` (enum, optional, default "newest") — Review order. [one of: newest, oldest, highest, lowest, most_helpful]
- `rating` (integer, optional) — Only reviews with this many stars.
- `page` (integer, optional, default 1) — Review page.
- `page_size` (integer, optional, default 20) — Reviews per page (1-100).

**Returns:** reviews[]{review_id, rating, rating_range, title, text, date, author, author_location, verified_purchaser, recommended, helpful_votes, unhelpful_votes, pros, cons, secondary_ratings{}, photos[], brand_responses[], syndicated_from, locale, bv_product_id} + total_reviews, summary{average_rating, total_submissions, ratings_only, recommended, not_recommended, distribution{}}, page, page_size, has_more

**Example request body:**
```json
{
  "entity_id": "1177214513"
}
```

## 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=worten
- Human docs page: https://reefapi.com/docs/worten
- Overview page: https://reefapi.com/worten-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt