1688 Product details API
API health
- 24h health
- 98%
- 24h average time
- 29.27 s
- Healthy / normal
- Available
- Limited
- Mostly down
Last 24 hours
Last 30 days
Fetch one 1688 offer by its product link or numeric offerId, with tiered pricing, minimum order quantity, stock, variants, specs, images and seller background. price_tiers lowers the unit price as quantity rises, and a missing variant field does not mean that variant is out of stock.
Send POST https://api.everyinfra.com/api/v1/social with platform set to alibaba1688 and action set to product_detail. Price $1.39 per 1,000 requests ($0.001389 per call). Failed calls and empty results are not charged. Synchronous. For slow jobs add "mode": "async" to the body, take the job_id and poll.
1688 Product details reads the full public record of one wholesale product: price range and tiered prices, minimum order quantity and pricing unit, stock and sales, variant details, rating and positive-review rate, images, and the supplier's name, type, founding year, followers and favorites, plus whether it offers samples and dropshipping. Use it to decide whether buying from this supplier makes sense, for purchase evaluation and supplier comparison.
url takes a 1688 product link, share text with exactly one product link, or a numeric offer ID; shop home pages and search pages are rejected. Read prices with price_tiers, where the unit price falls as quantity rises. positive_rate is a fraction from 0 to 1, not a percentage. Options, prices and stock in skus appear only when the platform states them, so a missing value does not mean out of stock.
AI prompt
#Please help me write a data collection script with the EveryInfra 1688 Product details endpoint (alibaba1688/product_detail).
How the endpoint works:
- Request: POST https://api.everyinfra.com/api/v1/social with the header Authorization: Bearer <API key>. Read the key from the EVERYINFRA_API_KEY environment variable and never hard-code it.
- In the request body, set platform to alibaba1688 and action to product_detail, and put the parameters inside params.
- Required parameters:
- url: For product_detail, use a product URL on detail.1688.com or m.1688.com, a share message containing exactly one product URL, or a numeric offerId.
- Returns one object. Main fields: id, url, title, text, price_min (Lower bound of the price range), price_max (Upper bound of the price range), currency, price_tiers (Tiered prices: the unit price falls as…), min_order_quantity (Minimum order quantity (MOQ)), stock (Stock), sold_count (Units sold), category (Category name in the platform's own tax…); 68 fields in total, full list at https://api.everyinfra.com/api/v1/social/catalog?platform=alibaba1688.
- Example request body:
{
"platform": "alibaba1688",
"action": "product_detail",
"params": {
"url": "https://detail.1688.com/offer/873514490218.html"
}
}
- Price: $1.39 per 1,000 requests; failed and empty results are not charged.
- For dozens or hundreds of targets, add "mode": "async" to the body: you get a job_id at once and poll GET https://api.everyinfra.com/api/v1/jobs/{job_id} for the result.
- On 422, fix the request using the suggested parameter names and allowed values in the error; on 429 or 503, wait for Retry-After and try again.
Before writing code, ask me which targets I need, how many, which fields, and what output format I want; then confirm the plan and the rough cost with me.Request parameters
#| Name | In | Type | Required | Default | Description |
|---|---|---|---|---|---|
Authorization | header | string | Yes | - | Bearer followed by your API key. Create it in the console; never put it in a URL or a code repository. |
platform | body | string | Yes | alibaba1688 | Platform identifier, fixed value. |
action | body | string | Yes | product_detail | Capability identifier, fixed value. |
url | body.params | string | Yes | - | For product_detail, use a product URL on detail.1688.com or m.1688.com, a share message containing exactly one product URL, or a numeric offerId. A qr.1688.com share link is accepted only if it safely resolves to a product page. Storefront and search pages are rejected. When the product has been taken down or does not exist, the result is empty with empty_reason item_not_found and nothing is charged; a repeat for the same product within 24 hours returns the same result, also free. |
Code samples
#curl -X POST 'https://api.everyinfra.com/api/v1/social' \
-H "Authorization: Bearer $EVERYINFRA_API_KEY" \
-H 'Content-Type: application/json' \
--data-raw '{
"platform": "alibaba1688",
"action": "product_detail",
"params": {
"url": "https://detail.1688.com/offer/873514490218.html"
}
}'OpenAPI definition (JSON)Samples read the key from the EVERYINFRA_API_KEY environment variable; copied code never contains your key.
Response example
#{ "id": "req_…", "platform": "alibaba1688", "action": "product_detail", "results": { "id": "•••", "url": "https://detail.1688.com/offer/873514490218.html", "title": "跨境专供Pro6蓝牙耳机真无线入耳式超长续航tws运动无线蓝牙耳机", "price_min": 7.1, "price_max": 13.8, "currency": "CNY", "min_order_quantity": 2, "stock": 7682692, "sold_count": 16813, "category": "蓝牙耳机", "unit": "条", "supplier_name": "深圳高耳基科技有限公司", "supplier_fans": "582", "supplier_type": "normal_factory", "supplier_favorited_count": 582, "supports_dropship": { "enabled": false, "consignPrice": null, "consignPriceTiers": [], "channels": [], "channelDetails": [], "protections": [], "downstreamPerformance": null, "metrics": { "orders30d": null, "orders7d": null, "pickupRate48h": null, "pickupRate24h": null, "distributorCount": null, "downstreamStoreCount": null, "publishDate": null } }, "supports_sampling": false, "is_out_of_stock": false, "skus": [ { "id": "•••", "name": "Pro6蓝牙耳机 紫色", "options": { "颜色": "Pro6蓝牙耳机 紫色" }, "price": 7.6, "original_price": 7.6, "stock": 665434, "available": true, "image_url": "https://cbu01.alicdn.com/img/ibank/O1CN01ngwdIg1fNlJ87ZHWL_!!2218564053995-0-cib.jpg" }, { "id": "•••", "name": "八代蓝牙耳机简配", "options": { "颜色": "八代蓝牙耳机简配" }, "price": 9.6, "original_price": 9.6, "stock": 666024, "available": true }, { "id": "•••", "name": "Pro6蓝牙耳机 粉色", "options": { "颜色": "Pro6蓝牙耳机 粉色" }, "price": 7.6, "original_price": 7.6, "stock": 664567, "available": true, "image_url": "https://cbu01.alicdn.com/img/ibank/O1CN01VHBm431fNlJGJw3Jm_!!2218564053995-0-cib.jpg" } ], "images": [ "https://cbu01.alicdn.com/img/ibank/O1CN01RrMK531fNlLKVri2p_!!2218564053995-0-cib.jpg", "https://cbu01.alicdn.com/img/ibank/O1CN01oiS7FO1fNlJFcPVcJ_!!2218564053995-0-cib.jpg", "https://cbu01.alicdn.com/img/ibank/O1CN019hrirk1fNlJGpWQke_!!2218564053995-0-cib.jpg" ], "description_images": [ "https://cbu01.alicdn.com/img/ibank/O1CN01xDu8VE1fNlOMt4i8Z_!!2218564053995-0-cib.jpg", "https://cbu01.alicdn.com/img/ibank/O1CN01mTmUSS1fNlONCMZWr_!!2218564053995-0-cib.jpg", "https://cbu01.alicdn.com/img/ibank/O1CN01myoX5I1fNlONcSew0_!!2218564053995-0-cib.jpg" ], "video_url": "https://cloud.video.taobao.com/play/u/2218564053995/p/2/e/6/t/1/482069395965.mp4", "specs": [ { "name": "芯片类型", "value": "中科蓝讯" }, { "name": "功能", "value": "防水,降噪,呼吸灯,超长续航,通话功能,语音控制,支持音乐,数显屏幕,电竞低延迟" }, { "name": "续航时间", "value": "0-4小时" } ], "rating": 4.7, "review_count": 20, "positive_rate": 0.95, "sold_display": "已售2.2万+件", "want_buy_count": 127, "category_path": "数码、电脑 > 手机配件 > 蓝牙耳机", "services": [ "7天无理由退货", "晚发必赔" ], "winport_url": "https://winport.1688.com/page/index.html?memberId=b2b-2218564053995870c8&_tabId_=index&upstreamSource=od&offerId=873514490218", "platform": "1688", "rating_scale": 5 }, "billing": { "charged": …, "charged_usd": …, "balance_after_usd": …, … }, "quota": { … }}
Response fields
#Business data is in results. The table lists the fields a record can contain; values the platform does not show are never made up.
| Field | Meaning |
|---|---|
id | The record's unique ID on the platform. Unique only within one platform; IDs can repeat across platforms. |
url | Link to the record on the platform. |
title | Title. null when the platform has no titles (for example text-only posts). |
text | Body text with HTML removed, returned in full and never cut short (on a few platforms the list results themselves carry only an excerpt; the platform's field notes say so). |
price_min | Lower bound of the price range. |
price_max | Upper bound of the price range. |
currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
price_tiers | Tiered prices: the unit price falls as the order quantity rises. Read each tier with its minimum quantity. |
min_order_quantity | Minimum order quantity (MOQ). The first threshold in 1688 wholesale buying: check it before anything else. |
stock | Stock. In product details it may be empty on a sync call; an async call usually returns it. |
sold_count | Units sold. |
category | Category name in the platform's own taxonomy, not normalized across platforms. In product details it may be empty on a sync call; an async call usually returns it. |
unit | Pricing unit (piece, item, carton and so on). |
supplier_name | Supplier name. |
supplier_fans | Supplier follower count. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_founded_year | Year the supplier was founded. |
supplier_type | Supplier business mode (e.g. manufacturer, wholesaler). In product details it may be empty on a sync call; an async call usually returns it. |
supplier_favorited_count | Number of times the supplier was added to favorites. In product details it may be empty on a sync call; an async call usually returns it. |
supports_dropship | Whether the supplier ships single units on your behalf (dropshipping). A key filter for selling without holding stock. In product details it may be empty on a sync call; an async call usually returns it. |
supports_sampling | Whether the supplier offers samples. In product details it may be empty on a sync call; an async call usually returns it. |
is_out_of_stock | Whether the product is out of stock. In product details it may be empty on a sync call; an async call usually returns it. |
skus | Variant details where available. Each row's options, price, stock and availability are returned only when the platform data states them; a missing value does not mean out of stock. In product details these variant fields may be empty on a sync call: weight_g, length_cm, width_cm, height_cm, volume_cm3, image_url, original_price; use an async call when you need them. |
images | Main product image links in page order; in product_detail some listings also include variant (SKU) images, and description-area images are in description_images. Absent when there are no images. |
description_images | Detail-description image URL list, in the listing's original order; null when the listing has none. In product details it may be empty on a sync call; an async call usually returns it. |
video_url | Product video URL, when the listing has one. |
specs | Product specification table: list of {name, value} pairs (e.g. Material: TPU). In product details it may be empty on a sync call; an async call usually returns it. |
rating | Overall product rating (1-5). In product details it may be empty on a sync call; an async call usually returns it. |
rating_scale | Maximum of rating in the same row: 5 for five-star scales, 10 for ten-point scales. Present only when the row has a rating. In product details it may be empty on a sync call; an async call usually returns it. |
review_count | Total review count. In product details it may be empty on a sync call; an async call usually returns it. |
positive_rate | Positive-review rate as a 0-1 fraction (0.999 = 99.9%). In product details it may be empty on a sync call; an async call usually returns it. |
sold_display | Sales as originally displayed (Chinese source text, e.g. 100k+ sold); for the numeric figure use sold_count. In product details it may be empty on a sync call; an async call usually returns it. |
want_buy_count | Number of buyers who marked the listing as wanted (a sourcing-demand signal). In product details it may be empty on a sync call; an async call usually returns it. |
category_path | Full category path with Chinese segment names (e.g. Digital > Phone accessories > Phone case, in the source language). In product details it may be empty on a sync call; an async call usually returns it. |
services | Listing service labels (e.g. free return shipping, late-delivery compensation). In product details it may be empty on a sync call; an async call usually returns it. |
promotions | Names of promotions currently in effect. |
customization_supported | Whether the supplier supports customization (custom artwork, sampling). In product details it may be empty on a sync call; an async call usually returns it. |
winport_url | Supplier's 1688 storefront link. |
city | City name in the platform's language, not normalized. In product details it may be empty on a sync call; an async call usually returns it. |
province | Province where the supplier is based. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_years | Years the supplier has been on the 1688 platform. In product details it may be empty on a sync call; an async call usually returns it. |
package_dimensions | Keeps the platform's own meaning |
coupons | Keeps the platform's own meaning |
promotion_details | Keeps the platform's own meaning |
service_details | Service guarantee details: code (service code), name, description (the rule), rule_url (rule page). services / service_tags give names only. In product details it may be empty on a sync call; an async call usually returns it. |
purchase_limits | Keeps the platform's own meaning |
mix_wholesale | Keeps the platform's own meaning |
supports_mix | Whether the listing accepts mixed orders (combining different styles to meet the minimum order quantity). In product details it may be empty on a sync call; an async call usually returns it. |
review_tags | Buyer impression tags: [{tag, count}], for example “soft fabric” ×2. In product details it may be empty on a sync call; an async call usually returns it. |
refund_rate | Keeps the platform's own meaning |
review_negative_count | Keeps the platform's own meaning |
review_neutral_count | Keeps the platform's own meaning |
review_with_photo_count | Number of reviews with photos; null means not provided, not 0. In product details it may be empty on a sync call; an async call usually returns it. |
review_with_text_count | Number of reviews with text; null means not provided, not 0. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_stats | Supplier profile (only keys with values): employee_count, plant_area_sqm (factory area in m²), plant_type (for example, own factory), equipment_count (main equipment), product_count (products on sale), repeat_rate (repeat-buyer rate, 0-1), repeat_buyer_count_text / cross_border_buyer_count_text (repeat and cross-border buyers as shown, such as 300+), response_rate (0-1), positive_review_rate (0-1), fulfillment_rate (0-1), certificate_count / certificates / management_certificates (certificate count, names and management-system certifications), patent_count, oem_mode (OEM/ODM), own_brands (own brands as shown), brand_count, partner_brand, is_major_brand_partner (supplies major brands), scale_tier (size tier), honors. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_scores | Keeps the platform's own meaning |
supplier_metric_tags | Keeps the platform's own meaning |
supplier_rank | Keeps the platform's own meaning |
supplier_industry_belt | Industrial-cluster certification: description (for example, a 1688-certified flagship merchant of a regional apparel cluster), link_url (certification page). In product details it may be empty on a sync call; an async call usually returns it. |
supplier_certification | Third-party factory or business audit: agency (auditor code, such as sgs or tuv), report_number (report number as shown), report_url (report page). In product details it may be empty on a sync call; an async call usually returns it. |
supplier_verification_tags | Keeps the platform's own meaning |
supplier_inspection_report_url | Keeps the platform's own meaning |
supplier_videos | Keeps the platform's own meaning |
supplier_address | Supplier address as shown. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_coordinates | Supplier location: {longitude, latitude}. In product details it may be empty on a sync call; an async call usually returns it. |
supplier_main_category | Supplier's main category. In product details it may be empty on a sync call; an async call usually returns it. |
customization | Keeps the platform's own meaning |
shipping | Keeps the platform's own meaning |
unit_weight_kg | Weight of one unit, in kilograms. In product details it may be empty on a sync call; an async call usually returns it. |
platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |
FAQ
#How do I read tiered prices?
#price_tiers lists the unit price for each quantity band, falling as you buy more. min_order_quantity is the minimum order and unit the pricing unit. To estimate cost, find the band your planned quantity falls in.
How can I tell a factory from a trading company?
#supplier_type says whether the supplier is a manufacturer or a trading company. Read it with supplier_founded_year, supplier_fans and supplier_favorited_count to judge how long the supplier has operated and how much attention it gets.
Does a variant without stock data mean it is sold out?
#Not necessarily. Options, prices, stock and availability in skus are returned only when the platform states them, so a gap is not a sell-out. Check is_out_of_stock for the product as a whole. On a sync call stock, positive_rate, supports_dropship and other fields (category, reviews, services, supplier profile, variant size and weight; the field list names them all) may be empty; use an async call when you need them.
Errors and billing
#- 401
- Missing or invalid key.
- 402
- Insufficient balance. Top up first.
- 422
- Invalid parameter name or value. Fix it using the suggestions in the error. No charge.
- 429
- Per-minute request limit reached. Wait for Retry-After, then try again.
- 503
- Could not complete. The held charge is returned to your balance. If the outcome is unknown, verify it before you retry.
- 200 empty
- No data. No charge.
Official references
#Used only to check objects and terms. They do not imply authorization or endorsement of EveryInfra by the platform.
- 1688: Products, Specifications, and Minimum Order Quantities ↗
1688 procurement documentation distinguishes among product offerId, specification specId, and purchase quantity, and separately validates minimum order quantity. These terms are cited here for explanatory purposes only; this endpoint does not create or preview purchase orders.
Checked 2026-09-04