1688 API
For 1688, this page separates keyword discovery, single-image product matching, and one-offer details across search, image_search, and product_detail.
Use search for product terms, image_search for one public image and up to five similar 1688 offers, and product_detail for the SKU and quantity-break information available on one identified offer.
Platform availability
- 24h health
- Normal
Last 30 days
Available capabilities
Each 1688 action, what it does, its price and its health over the last 24 hours. Open an action for its parameters, response fields and code samples.
| Capability | What it does | Per 1,000 | 24-hour health |
|---|---|---|---|
Searchsearch | List 1688 wholesale offers for a product keyword, with price range, minimum order quantity, order count, repurchase rate and seller details. | $1.39 per 1,000 requests | Normal |
Product detailsproduct_detail | Fetch one 1688 offer by its product link or numeric offerId, with tiered pricing, minimum order quantity, stock, variants, specs, images and seller background. | $1.39 per 1,000 requests | Normal |
In-platform product image searchimage_search | Match one product photo in image_url against 1688 and get up to five similar wholesale offers with title, CNY price, minimum order, seller and link. | $5.56 per 1,000 requests | Normal |
Open a capability for its parameters, response fields, code samples and trial.
What does each 1688 action accept?
Each answer below pairs one callable action with its real inputs. Parameter meanings and allowed values are action-specific; a familiar name does not carry the same meaning across every platform.
Official sources are linked only to clarify the platform term beside them. They do not imply platform authorization or endorsement, and they do not add official-site features to the EveryInfra API contract.
| Action | Required | Optional | Delivery | Limit | Per 1,000 | Response fields |
|---|---|---|---|---|---|---|
searchSearch List 1688 wholesale offers for a product keyword, with price range, minimum order quantity, order count, repurchase rate and seller details. Neither the sort order nor | keyword | city, max_price, min_price, sort | Sync delivery | Catalog values: defaultLimit=20, maxLimit=100. A limit can control pages or per-parent expansion for some actions, so it is not always a final row count. | $1.39 per 1,000 requests | id · url · title · text · price_min · price_max · currency · min_order_quantity · order_count · repurchase_rate · category · city · province · supplier_name · is_out_of_stock · supports_dropship · images · supplier_type · supplier_years · supplier_shop_url · supplier_composite_score · sold_count_text · service_tags · product_badges · platform |
product_detailProduct details Fetch one 1688 offer by its product link or numeric offerId, with tiered pricing, minimum order quantity, stock, variants, specs, images and seller background. | url | — | Sync delivery | — | $1.39 per 1,000 requests | id · url · title · text · price_min · price_max · currency · price_tiers · min_order_quantity · stock · sold_count · category · unit · supplier_name · supplier_fans · supplier_founded_year · supplier_type · supplier_favorited_count · supports_dropship · supports_sampling · is_out_of_stock · skus · images · description_images · video_url · specs · rating · rating_scale · review_count · positive_rate · sold_display · want_buy_count · category_path · services · promotions · customization_supported · winport_url · platform |
image_searchIn-platform product image search Match one product photo in | image_url | — | Sync delivery | Catalog values: defaultLimit=5, maxLimit=5. A limit can control pages or per-parent expansion for some actions, so it is not always a final row count. | $5.56 per 1,000 requests | id · url · title · price · currency · min_order_quantity · order_count · supplier_name · image_url · rank · platform |
What do the 1688 search parameters mean?
List 1688 wholesale offers for a product keyword, with price range, minimum order quantity, order count, repurchase rate and seller details. Neither the sort order nor order_count proves exact sales or a final quote.
keywordRequired- Specifies the search term for 1688 wholesale products (for example, insulated mugs or cardboard boxes). Use product terms rather than store names or offerIds; minimum order quantities and tier pricing return inside item details.
cityOptional- Filters 1688 wholesale item queries by city name text. This filter does not reflect account locations, change returned seller addresses, or guarantee persistent filtering on single-product detail requests.
max_priceOptional- Filters wholesale items by maximum unit price as a numeric value. It operates alongside min_price to bound price ranges rather than tier order quantities, and it may not cover every SKU variant or volume discount tier.
min_priceOptional- Filters wholesale items by minimum unit price as a numeric value. This parameter sets item criteria rather than minimum order quantities or API spend limits, and returned tier pricing varies by order volume.
sortOptional- Sorts search items by relevance (default for search), popular, price_asc, or price_desc. Sorting criteria do not guarantee exact sales figures or total transaction amounts in the payload.Allowed values:
popularprice_ascprice_descrelevance
What do the 1688 product_detail parameters mean?
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.
urlRequired- 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.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
What do the 1688 image_search parameters mean?
Match one product photo in image_url against 1688 and get up to five similar wholesale offers with title, CNY price, minimum order, seller and link. rank is the match order for this image, not a sales ranking.
image_urlRequired- For image_search, provide one public HTTPS product-image URL. The action submits one image, returns at most five matching 1688 offers, and does not include detail or SKU enrichment.1688 Open Platform: Finding Similar Products from an Image — 1688's open platform documents an official similar-product lookup that accepts an image URL or image content. This source establishes the platform-level image-to-product object only; EveryInfra's single-image limit, maximum of five results, response allowlist, billing, and delivery behavior remain defined by its own published contract. · Checked
How to use the 1688 API
- 01Read the public catalog and choose a platform action.
- 02Send the platform, action, and required parameters to POST /api/v1/social.
- 03Handle a synchronous result, or poll the returned job ID when the action runs asynchronously.
- 04Store the structured response fields needed by your application.
curl -X POST https://api.everyinfra.com/api/v1/social \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"platform":"alibaba1688","action":"search","params":{"keyword":"<keyword>"}}'
1688 guides
Worked examples and methods built on these actions. Check the current actions, parameters and fields on this page first; an article's examples and limits do not replace the live catalog.
Commercializing Price Scraping: Building a Price Monitoring Product Merchants Will Renew
Why merchants pay for price monitoring and why they cancel subscriptions. Examine price data delivery methods, pricing units, and pilot acceptance through product matching, exception lists, and pricing approval workflows.
Read the article →Unified Data API Getting Started: From Capability Catalog to First Available Result
Access multi-platform data using platform, action, and params: read the capability catalog, complete minimal requests, handle asynchronous tasks, partial results, and billing, and establish traceable data records.
Read the article →API Failures, Credit Returns, and Reconciliation: How to Audit the Net Charge of a Request
Separate tasks, call attempts, delivery states, and wallet events to handle pre-charge rejections, empty results, and partial credit returns without double-counting, using integer-based offline examples.
Read the article →1688 API questions
What can I retrieve with the 1688 API?
Set platform to alibaba1688. The current catalog lists search, product details, and in-platform product image search. These action names identify different 1688 objects or views; they are not interchangeable search modes.
Does 1688 have an official API?
Alibaba's 1688 Open Platform is built for software vendors that make tools for 1688 sellers and for buyers who source or dropship from 1688, such as listing, order management and cross-border purchasing tools; it lists more than 1,600 partner vendors.
Official sources: 1688 Open Platform · Checked
Do I need a 1688 developer account or API key?
No. Requests go through EveryInfra with an EveryInfra API key: sign up, create a key in the console and send it as Authorization: Bearer <API_KEY>. You do not register a 1688 developer app, apply for 1688 API access or sign in with a 1688 account, and the actions return public 1688 data only.
How much does the 1688 API cost per 1,000 requests?
$1.39–$5.56 per 1,000 requests, depending on the action; each action's price is listed in the table on this page and in the public catalog. There is no subscription: you top up a USD balance and pay per call, and failed calls and empty results are not charged.
Which input starts a 1688 `search` request?
Specifies the search term for 1688 wholesale products (for example, insulated mugs or cardboard boxes). Use product terms rather than store names or offerIds; minimum order quantities and tier pricing return inside item details. Send it as keyword inside params.
Which fields can 1688 `search` return?
Its declared schema includes title, text, price_min, and price_max. A declared field can still be absent from an individual record, and every other action has its own field list.
Does every 1688 action return immediately?
Actions labeled asynchronous return a job ID you poll. Every other action can also run asynchronously: add "mode": "async" to the request body to receive a job ID immediately, useful for slow tasks or large limits. The current catalog contains sync delivery.