1688 APIs.1688.com ↗
Search 1688.com wholesale products, fetch SKU pricing tiers, and retrieve customer reviews via 3 structured endpoints covering China's largest B2B marketplace.
What is the 1688 API?
The s.1688.com API provides 3 endpoints covering product search, detailed SKU data, and customer reviews from China's largest B2B wholesale marketplace. The search_products endpoint returns paginated results with offer IDs, seller names, pricing, and geographic location, while get_product_detail exposes full SKU model data including pricing tiers, variant properties, and promotion info — giving developers structured access to supplier and product data without manual browsing.
curl -X GET 'https://api.parse.bot/scraper/aa6e2b5e-7963-46f5-a6c2-e326775ceae4/search_products?page=1&query=ceramic+mug' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace s-1688-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: 1688.com Product API — search, drill into details and reviews."""
from parse_apis._1688_com_Product_API import Alibaba1688, NotFoundError
client = Alibaba1688()
# Search for products — limit= caps total items fetched across all pages.
for item in client.product_summaries.search(query="ceramic mug", limit=5):
print(item.title, item.price, item.image_url, item.city)
# Drill into one result for full SKU detail.
first = client.product_summaries.search(query="LED light", limit=1).first()
if first:
detail = first.details()
if detail.sku_model and detail.sku_model.sku_selector_biz_model:
biz = detail.sku_model.sku_selector_biz_model
print(detail.offer_id, biz.sku_price_scale)
if biz.sku_props:
for prop in biz.sku_props:
print(prop.prop, [v.name for v in prop.value])
# Fetch reviews for a product via the sub-resource.
if first:
for review in first.reviews.list(login_id=first.login_id, limit=3):
print(review.star_level, review.content)
# Direct product detail lookup by offer_id.
try:
product = client.products.get(offer_id="1027530641922")
print(product.offer_id)
except NotFoundError as exc:
print(f"Product not found: {exc}")
print("exercised: product_summaries.search / details / reviews.list / products.get")
Full-text search over 1688.com product listings by keyword. Returns a paginated list of product offers with seller info, pricing, and location. Each page returns up to 40 items. Paginates via integer page counter. Results include enough seller context (loginId) to drill into reviews.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number for pagination |
| queryrequired | string | Search keyword (Chinese or English) |
{
"type": "object",
"fields": {
"page": "integer current page number",
"items": "array of product objects with offerId, title, price, imageUrl, loginId, sellerName, bookedCount, province, city, url",
"total": "integer total number of results",
"hasMore": "boolean indicating if more pages are available"
},
"sample": {
"data": {
"page": 1,
"items": [
{
"url": "https://detail.1688.com/offer/1027530641922.html",
"city": "梁山县",
"price": "3.9",
"title": "11oz热升华空白涂层杯 欧美AAA级Sublimation Mug热转印马克杯",
"loginId": "梁山晟恒科贸",
"offerId": 1027530641922,
"province": "山东",
"sellerName": "梁山晟恒科贸有限公司",
"bookedCount": "6"
}
],
"total": 2000,
"hasMore": true
},
"status": "success"
}
}About the 1688 API
Search and Discovery
The search_products endpoint accepts a query string (Chinese or English) and an optional page integer for pagination. Each result object includes offerId, title, price, loginId, sellerName, bookedCount, province, city, url, and a hasMore flag alongside the total count. The bookedCount field indicates order volume and is useful for gauging supplier activity. Geographic fields (province, city) help identify where the seller operates within China.
Product Detail and SKU Modeling
The get_product_detail endpoint takes an offer_id (the numeric offerId from search results) and returns the full skuModel object. This object contains SKU selector data covering pricing tiers, variant properties (such as size or color), associated images, trade model constraints, and active promotion info. Pricing tiers are a core part of 1688 wholesale listings, where unit cost typically decreases at higher quantity thresholds.
Customer Reviews
The get_product_reviews endpoint requires both an offer_id and a login_id — the seller's login identifier returned in search_products results. It returns a reviews array and a headers metadata object. Note that the reviews array may be empty if a product has no recorded reviews. Pagination is supported via the page parameter. The login_id dependency means you must either run a search or fetch product detail before calling reviews.
The 1688 API is a managed, monitored endpoint for s.1688.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when s.1688.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official s.1688.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Compare unit pricing tiers across multiple 1688 suppliers for the same product category using
skuModeldata fromget_product_detail. - Build a supplier shortlist by filtering
search_productsresults byprovinceorcityto find geographically clustered manufacturers. - Track
bookedCountacross keyword searches to identify high-demand wholesale products. - Aggregate customer reviews from
get_product_reviewsto score supplier reliability before placing bulk orders. - Map
offerIdtosellerNameandloginIdfor structured supplier databases populated from search results. - Monitor SKU variant availability and promotional pricing changes by polling
get_product_detailfor specific offer IDs. - Seed a product catalog with wholesale pricing from 1688.com by combining search pagination with per-offer detail lookups.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does 1688.com have an official developer API?+
What does the `skuModel` object in `get_product_detail` actually contain?+
skuModel object includes SKU selector data covering pricing tiers (wholesale quantity brackets), variant properties such as size or color, images tied to specific SKU combinations, the trade model (e.g. minimum order quantities), and any active promotion info. It is the primary source for per-variant pricing on a 1688 listing.Why does `get_product_reviews` require a `login_id` in addition to an `offer_id`?+
login_id is the seller's account identifier and is returned in the loginId field of search_products results. You need to run a search or hold a prior result to supply this parameter when calling the reviews endpoint.Does the API return seller certification, business license, or factory audit data?+
Are there limitations on review data availability?+
reviews array can be empty if a product has no posted reviews, which is common for newer or lower-volume listings on 1688.com. The endpoint does not distinguish between a product with zero reviews and one where reviews are restricted — both return an empty array. Pagination via page applies only when reviews exist.