# Shein — product search, product detail and price/stock refresh

> Return JSON product cards from the selected storefront with local prices, currency and product URLs. Global and regional search support page=1 and up to 40 results. US search retains pagination. Source totals can exceed returned rows; there is no automatic regional pagination. Global is the default.
> ReefAPI engine `shein` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/shein/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/shein/v1/search — 4 credits
Return JSON product cards from the selected storefront with local prices, currency and product URLs. Global and regional search support page=1 and up to 40 results. US search retains pagination. Source totals can exceed returned rows; there is no automatic regional pagination. Global is the default.

**Parameters:**
- `query` (string, required) — Search phrase.
- `market` (enum, optional, default "global") — Select the storefront and its local currency. [one of: global, us, sa, ae, kw]
- `max_results` (integer, optional, default 40) — Global: at most 40 results on page 1. US: auto-paginate up to 600 results.
- `page` (integer, optional, default 1) — Result page. Empty page = end of list.
- `limit` (integer, optional, default 40) — Global: 1-40 results. US: 1-120 per page. Default 40 in the playground.
- `category_id` (string, optional) — Optional Shein category id -- the number in a /-c-<id>.html URL (1727 = Women Short Dresses), or the URL itself. Restricts the search to that category and its sub-categories (measured: query=women returns 14963 matches unfiltered and 9092 with category_id=2030). US storefront only; a keyword is still required.

**Returns:** results[]{goods_id, name, url, price, list_price, discount_pct, currency_code, image, images[], rating, reviews_count, colors[], fit_true_size_pct, category, brand, store_name, in_stock} + query + page + has_next; global also returns pagination_supported=false + source_has_more. meta.result_count is Shein's own total match count, and meta.rows_withheld_by_source counts rows Shein listed as matches but refused to serve card data for on this page (0 in the normal case). With category_id the response echoes category_id and meta carries category_leaf_ids

**Example request body:**
```json
{
  "query": "summer dress",
  "max_results": 20
}
```

### POST https://api.reefapi.com/shein/v1/product/detail — 4 credits
Read a complete selected regional product page in its local currency, by product id or URL. Includes current page prices, all published SKUs with size and stock, total stock, images, and available size charts, attributes and description. These fields are included by default. sizes[] carries each size's price, list_price and base_price next to its stock. Shein runs price tests: two shopper sessions can see different promotional prices for the same product. price is the offer of the session that read the page; base_price (the price before any promotion) and list_price are the same for every session, and price_test_applied tells whether the test discount is in price. Shein shows stock up to 20 per SKU: a stock of 20 means 20 or more (stock_is_minimum / total_stock_is_minimum). colors[] lists the colour variants with name, goods_id and swatch image. Optional fields/exclude shape the response; the raw source blocks are about 95% of its size. Unavailable global SKU prices are null and sku_prices_complete is false. Missing product prices return an error without additional price lookup requests. Prices can change; no global product is successful without a verified positive product price. Global is the default; an explicit market wins, otherwise a product URL selects its storefront. NOT_FOUND means the selected storefront returned a product 404. UPSTREAM_HTTP with error.detail.reason=global_offer_price_unavailable means a complete priced offer could not be supplied; it does not mean the product is free or permanently removed. These outcomes are not retried within the call. Transient failures remain retryable; inspect error.retryable. Billing: a verified NOT_FOUND (error.detail.reason=product_not_found) costs 4 credits per request, including when the product is absent from the selected market. The response stays ok=false and includes meta.charged_credits=4. Timeouts, capacity limits, blocked requests, parsing errors and unavailable-price errors are not charged.

**Parameters:**
- `goods_id` (string, optional) — Product id. Supply either goods_id or a product URL.
- `url` (string, optional) — Full product URL (alternative to goods_id).
- `market` (enum, optional, default "global") — Explicit market takes precedence. Otherwise infer from the product URL; id-only defaults to global. Global uses www.shein.com in USD; availability and shipping are destination-dependent. An unavailable global product price returns an error without additional price lookup requests. [one of: global, us, uk, de, fr, es, it, nl, pl, pt, se, tr, sa, ae, kw]
- `fields` (array, optional) — Return only these product keys (goods_id is always kept). Optional; the default is the full record. Applied keys are echoed in meta.field_selection.
- `exclude` (array, optional) — Drop these product keys. The raw source blocks (sale_attributes, skus, price_details, product_details, image_details, color_images, size_chart) are about 95% of a detail response; their useful values are already typed in sizes[], colors[], attributes[] and the price fields.

**Returns:** product{goods_id, goods_sn, name, price, price_display, list_price, base_price, promotion_discount, price_test_applied, currency_code, in_stock, total_stock, total_stock_is_minimum, brand (US), sizes[]{size, size_local, in_stock, stock, stock_is_minimum, sku_code, price, list_price, base_price}, colors[]{name, goods_id, image, url, is_current}, color, skus[], images[], color_names[], url, size_chart, sale_attributes, price_details, product_details, image_details, color_images, attributes[], description, price_source?, price_basis?, sku_prices_complete?}. Optional descriptive fields depend on what the source publishes.

**Example request body:**
```json
{
  "goods_id": "387752092",
  "market": "us"
}
```

### POST https://api.reefapi.com/shein/v1/price — 2 credits
Read current price and stock from the selected regional product page in its local currency. Returns only price and availability fields, including total stock. Prices reflect the offer at retrieval time and can change. It reads the same product page as product/detail. Shein runs price tests, so price can differ between sessions; base_price (before any promotion) is the same for every session and is the stable value for change detection. Missing product prices return an error without additional price lookup requests. Global is the default; an explicit market wins, otherwise a product URL selects its storefront. NOT_FOUND means the selected storefront returned a product 404. UPSTREAM_HTTP with error.detail.reason=global_offer_price_unavailable means a complete priced offer could not be supplied; it does not mean the product is free or permanently removed. These outcomes are not retried within the call. Transient failures remain retryable; inspect error.retryable. Billing: a verified NOT_FOUND (error.detail.reason=product_not_found) costs 4 credits per request, including when the product is absent from the selected market. The response stays ok=false and includes meta.charged_credits=4. Timeouts, capacity limits, blocked requests, parsing errors and unavailable-price errors are not charged.

**Parameters:**
- `goods_id` (string, optional) — Product id. Supply either goods_id or a product URL.
- `url` (string, optional) — Full product URL (alternative to goods_id).
- `market` (enum, optional, default "global") — Explicit market takes precedence. Otherwise infer from the product URL; id-only defaults to global. Global uses www.shein.com in USD; availability and shipping are destination-dependent. An unavailable global product price returns an error without additional price lookup requests. [one of: global, us, uk, de, fr, es, it, nl, pl, pt, se, tr, sa, ae, kw]

**Returns:** product{goods_id, price, price_display, list_price, base_price, promotion_discount, price_test_applied, discount_pct, currency_code, in_stock, total_stock, total_stock_is_minimum, url, price_source?, price_basis?, sku_prices_complete?}

**Example request body:**
```json
{
  "goods_id": "387752092",
  "market": "us"
}
```

### POST https://api.reefapi.com/shein/v1/category/browse — 1 credit
Shein refuses its category shelf for API clients, so this action reports that plainly instead of returning an empty or invented shelf. Measured 2026-09-25: the shelf endpoint refuses every request for a category id while the search endpoint answers normally in the same second from the same client, and the category page itself answers with a challenge. The error is not retryable, is never charged, and names the working route: call `search` with a keyword plus the same id as `category_id`, which returns the same product cards restricted to that category and its sub-categories. A keyword is required because Shein serves no products for a keyword-less category request.

**Parameters:**
- `category_id` (string, required) — Shein category id (the number in a /-c-<id>.html URL), or pass the category URL. Pass it to `search` as `category_id` together with a keyword.
- `market` (enum, optional, default "us") — Which Shein storefront to read. Prices and availability are per-storefront. [one of: us, uk, de, fr, es, it]
- `page` (integer, optional, default 1) — Result page. Empty page = end of list.
- `limit` (integer, optional, default 100) — Rows per page (max 120).

**Returns:** never returns rows; TARGET_BLOCKED with detail{category_id, reason, use_instead{action, params}} pointing at search + category_id

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

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