# 1688.com API scraper - live wholesale search and full product detail for 1688.com, Alibaba's China-domestic B2B marketplace. Every result carries the correct unit price, minimum order quantity, the quantity price ladder, supplier company and city; product detail adds per-variant price, stock and kg weight. No account, no browser.

> Search 1688 by keyword and get wholesale offers back. Chinese returns the richest results; English works. Every row carries the offer id and url, the title, the image gallery, the unit price in CNY with its unit, the seller's company name and years on 1688, BOTH repeat-purchase rates (the offer's own and the shop's - the single most useful trust signal on 1688), the product attribute pairs the seller published, the service tags, the category ids the offer sits under, and whether the row is a paid placement. Two honest limits, both measured rather than assumed. This surface serves ONE shortlist of about 20 offers per keyword and does not paginate: `has_next` is always false, and calling it repeatedly returns a rotating selection that saturates near 38 distinct offers. And it carries no MOQ and no price ladder - `product/detail` has both. For depth, take `category_ids` off a row and page `category/offers`, which does paginate for real.
> ReefAPI engine `1688` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/1688/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/1688/v1/search — 2 credits
Search 1688 by keyword and get wholesale offers back. Chinese returns the richest results; English works. Every row carries the offer id and url, the title, the image gallery, the unit price in CNY with its unit, the seller's company name and years on 1688, BOTH repeat-purchase rates (the offer's own and the shop's - the single most useful trust signal on 1688), the product attribute pairs the seller published, the service tags, the category ids the offer sits under, and whether the row is a paid placement. Two honest limits, both measured rather than assumed. This surface serves ONE shortlist of about 20 offers per keyword and does not paginate: `has_next` is always false, and calling it repeatedly returns a rotating selection that saturates near 38 distinct offers. And it carries no MOQ and no price ladder - `product/detail` has both. For depth, take `category_ids` off a row and page `category/offers`, which does paginate for real.

**Parameters:**
- `query` (string, required) — What to search 1688 for. Chinese returns by far the richest results (1688 is a China-domestic wholesale market); an English or pinyin term also matches. Returns wholesale offers with the correct unit price, minimum order quantity, quantity price ladder, supplier company and location.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** items[]{id, title, url, image, images[], video, price (number, CNY), price_display, currency, unit, sold_display, attributes[]{name, value}, service_tags[], offer_repurchase_rate, shop_repurchase_rate, seller{company, login_id, member_id, years_on_1688}, category_ids[], is_ad}, count, query, query_echo, has_next

**Example request body:**
```json
{
  "query": "蓝牙耳机"
}
```

### POST https://api.reefapi.com/1688/v1/category/offers — 1 credit
Browse a 1688 category and page through it properly. This is the deep surface: consecutive pages were measured to share NO offer ids at all, 30 rows each, so you can walk a category rather than skim it. Every row carries the offer id and url, the title and image, the price in CNY, the MINIMUM ORDER QUANTITY, when the offer was listed, the supplier's fulfilment promises (collection-rate style guarantees) and any cross-border certifications on the listing. Get a category id from `categories`, or take `category_ids` off any `search` row to turn a keyword into a browsable category. Page size is fixed at 30 by 1688.

**Parameters:**
- `category_id` (string, required) — A 1688 category id. Get one from `categories`, or from any `search` row: each returns `category_ids` (broad to leaf) for the offer it describes.
- `page` (integer, optional, default 1) — 1-based page. This surface pages for real: consecutive pages were measured to share no offer ids at all, 30 rows each. Page size is fixed at 30 by the source.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** items[]{id, title, url, image, price, price_display, currency, moq, listed_on, fulfilment[], certifications[], sales}, count, category_id, page, has_next

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

### POST https://api.reefapi.com/1688/v1/supplier/search — 1 credit
Find VETTED FACTORIES that make something, rather than offers that sell it. This is 1688's own manufacturer shortlist and it answers the question a sourcing buyer actually has before contacting anyone: is this a real factory and is it any good. Each row carries the company name and location, years on 1688, HOW MANY WORKERS and the floor area in square metres, what it manufactures, its gold-manufacturer medal and level, its REPEAT-BUYER RATE, on-time and 30-day reply rates, whether a third party (SGS and similar) has audited it, and offer ids you can pass straight to `product/detail`. 🔴 Read this before you build on it: 1688 publishes a CURATED shortlist per keyword, not an index. Measured over 12 keywords, 8 returned factories and 4 returned none, with every call succeeding. An empty list is a real answer meaning 1688 has no vetted factory for that keyword; it is not an error and retrying will not change it. Expect a handful of rows, not a page.

**Parameters:**
- `query` (string, required) — What to search 1688 for. Chinese returns by far the richest results (1688 is a China-domestic wholesale market); an English or pinyin term also matches. Returns wholesale offers with the correct unit price, minimum order quantity, quantity price ladder, supplier company and location.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** items[]{name, member_id, url, location, years_on_1688, workers, floor_area_sqm, makes[], medal, medal_level, repeat_buyer_rate, on_time_rate, reply_rate_30d, third_party_audit, is_super_factory, offer_ids[]}, count, query, note

**Example request body:**
```json
{
  "query": "蓝牙耳机"
}
```

### POST https://api.reefapi.com/1688/v1/categories — 1 credit
1688's category tree, TRANSLATED. 54 top-level categories over three levels, and 1688 translates the names itself, so a caller who does not read Chinese can still pick a category: ask for English, Russian, Spanish, Portuguese, French, German, Japanese or Korean and every node also carries its original Chinese name. Use the ids with `category/offers`. Ask for depth 1 for the 54 top categories, 2 for the useful middle (the default), 3 for the full tree.

**Parameters:**
- `language` (enum, optional, default "en") — Language for the category names. 1688 translates the tree itself, so a Russian or English caller does not have to read Chinese to pick a category. The original Chinese name is returned alongside as `name_zh` either way. [one of: zh, en, ru, es, pt, fr, de, ja, ko]
- `depth` (integer, optional, default 2) — How many levels of the category tree to return. The full three levels are about 2.4 MB; two levels is the useful default and one level is the 54 top categories.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** items[]{id, name, name_zh, level, is_leaf, children[] | child_count}, count, language, depth

**Example request body:**
```json
{
  "language": "ru",
  "depth": 1
}
```

### POST https://api.reefapi.com/1688/v1/product/detail — 2 credits
Full detail for one 1688 offer, merged from the offer page and 1688's variant model in two calls. Returns the title, image gallery, the unit price in CNY, the price type (a shared quantity ladder vs per-variant pricing) and the full price ladder with the minimum quantity of each tier, the MOQ with its unit, total orderable stock, the mixed-batch terms sourcing buyers need, units sold, the full specification table (material, brand, model, ...), the supplier company with its member and login ids and storefront url, and EVERY sellable variant with its own price, stock (canBookCount, present on 100% of variants) and shipping weight in kg where the supplier published it (absent on many, returned as null - never inferred). Colour / size / spec axes are returned alongside the variants. A dead or invented offer id returns NOT_FOUND.

**Parameters:**
- `offer_id` (string, required) — A 1688 offer id (the digits in `m.1688.com/offer/<id>.html`) or a full offer url. Every `search` row returns the id as `id`.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** id, title, url, images[], price (number, CNY), price_display, currency, unit, price_type (rangePrice=a shared quantity ladder / skuPrice=priced per variant), price_tiers[]{min_qty, max_qty, price, price_display}, moq{quantity, unit}, stock, mix{supported, min_qty, min_amount}, sold_count, category{top_id, post_id}, attributes[]{name, value}, seller{member_id, user_id, login_id, name, url}, in_stock, variants{axes[]{name, values[]}, skus[]{sku_id, spec, price, discount_price, stock, sold_count, weight_kg}, count, price_range, price_type, ship_from_code}

**Example request body:**
```json
{
  "offer_id": "864971848115"
}
```

### POST https://api.reefapi.com/1688/v1/product/reviews — 1 credit
Buyer reviews for one 1688 offer: the average star rating (out of 5), the positive-feedback percentage, the total review count, and a page of individual reviews with their text, the quantity bought, the variant, buyer photos and the date. 1688 masks buyer nicknames itself. Some offers have no reviews yet - that returns an empty list with a zero count, not an error.

**Parameters:**
- `offer_id` (string, required) — A 1688 offer id (the digits in `m.1688.com/offer/<id>.html`) or a full offer url. Every `search` row returns the id as `id`.
- `max_rotations` (integer, optional, default 4) — How many datacentre exits to try before giving up (1688 runs a per-exit request budget on search; a fresh exit clears it). Raise it only if you see transient block errors.

**Returns:** rating (number, out of 5), rating_scale, good_percent (number), good_percent_display, review_count (number - a lower bound where 1688 prints '100+'), review_count_display, reviews[]{content, buyer, quantity, spec, images[], date, plus_user}

**Example request body:**
```json
{
  "offer_id": "864971848115"
}
```

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