Product API Guide
The following is the guide to the product API
Search products by keyword
View details: Search products
Language translation
Use the lang parameter to translate the language of search results. The value of lang is described in the table below:
| Value | Description | Platform |
|---|---|---|
| vi | Vietnamese | ✅ Taobao ✅ 1688 |
| en | English | ✅ Taobao ✅ 1688 |
Translated data is in the titleEn key. The title key remains Chinese data.
Sort search results
Use the sort parameter to sort search results. The value of sort is described in the table below:
| Value | Description | Platform |
|---|---|---|
| PRICE_ASC | Price ascending | ✅ Taobao ✅ 1688 |
| PRICE_DESC | Price descending | ✅ Taobao ✅ 1688 |
| SALE_QTY_ASC | Sales quantity ascending | ✅ Taobao ✅ 1688 |
| SALE_QTY_DESC | Sales quantity descending | ✅ Taobao ✅ 1688 |
| RETENTION_ASC | Repurchase rate ascending | ❌ Taobao ✅ 1688 |
| RETENTION_DESC | Repurchase rate descending | ❌ Taobao ✅ 1688 |
Filter search results
Use the filter parameter to sort search results. The value of filter is described in the table below:
| Filter Criteria | Description | Platform |
|---|---|---|
| price_range | Price range (unit: CNY) | ✅ Taobao ✅ 1688 |
| shop_id | Products from same seller | ✅ Taobao ✅ 1688 |
| seller_level | Seller level | ❌ Taobao ✅ 1688 |
| is_factory | Only get products from super factories | ❌ Taobao ✅ 1688 |
| ffm_outbound | Fast outbound criteria | ❌ Taobao ✅ 1688 |
| ffm_delivery | Fast delivery criteria | ❌ Taobao ✅ 1688 |
| allow_return | 7-day no-reason return | ❌ Taobao ✅ 1688 |
| allow_dropship | Allow dropship | ❌ Taobao ✅ 1688 |
| freeship_for_dropship | Allow dropship + freeship | ❌ Taobao ✅ 1688 |
| new_arrival | Newly updated products on platform | ❌ Taobao ✅ 1688 |
| platform_pick | Platform-selected sources for domestic market | ❌ Taobao ✅ 1688 |
| global_pick | Platform-selected sources for international market | ❌ Taobao ✅ 1688 |
| dropship_pick | Platform-selected sources for dropship | ❌ Taobao ✅ 1688 |
Fast outbound criteria ffm_outbound
| Value | Description |
|---|---|
| FFMO1 | Shipment rate within 24h < 95% |
| FFMO2 | Shipment rate within 24h >= 95% |
| FFMO3 | Shipment rate within 24h > 99% |
| FFMO4 | Shipment rate within 48h < 95% |
| FFMO5 | Shipment rate within 48h >= 95% |
| FFMO6 | Shipment rate within 48h > 99% |
Fast delivery criteria ffm_delivery
| Value | Description |
|---|---|
| FFMD0 | Same day delivery |
| FFMD1 | Delivery within 24h |
| FFMD2 | Delivery within 48h |
Fast delivery criteria new_arrival
| Value | Description |
|---|---|
| 7DAY | Newly updated products in the last 7 days |
| 30DAY | Newly updated products in the last 30 days |
Seller level criteria seller_level
| Value | Description |
|---|---|
| L1 | Total rating 5 stars |
| L2 | Total rating 4.5 - 5 stars |
| L3 | Total rating 4 - 4.5 stars |
| L4 | Total rating below 4 stars |
Search products by image
Note: This feature does not apply to the Free plan.
View details: Search products
There are 2 ways to search products by image:
1. Search by image URL
Applicable scope: ✅ Taobao ✅ 1688
Use the img_url key in the parameter to query. However, only image links from Alibaba can be used: *.alicdn.com
2. Search by uploaded image
Applicable scope: ✅ Taobao ✅ 1688
To use this function, first upload the image to Alibaba server using the API Upload image. Then use the img_id key instead of img_url in the query parameter to make the request.
Get detailed product information
View details: Product details
If you frequently encounter short links like https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd, you must first process this link to get the original link.
Use the API Unshorten link to get the original link and product ID.
Explanation of product price types
| Price Attribute | Description | Platform |
|---|---|---|
| price | Regular price. For 1688, it’s wholesale price without freeship, quantity depends on seller settings. | ✅ Taobao ✅ 1688 |
| promotion_price | Promotion price, lower than or equal to regular price. | ✅ Taobao ✅ 1688 |
| retail_price | Retail price + freeship from 1 product, for dropshipping. Usually appears in selected 1688 products. | ❌ Taobao ✅ 1688 |
| dropship_price | Retail price for 1 item, usually equal to regular price. Difference depends on whether seller has active dropship. | ❌ Taobao ✅ 1688 |
Price display and application logic
Some products may have multiple price types. Price display and application logic depends on the platform. Additionally, prices via API may be higher than prices viewed directly on taobao/1688 websites. This is because website price mechanisms may have applied promotions, discounts, or other promotional programs. API prices cannot apply these complex promotional programs.
For taobao, priority is given to displaying and applying promotion prices. If no promotion price exists, use regular price.
For 1688, price application logic depends on the value of the quote_type field:
| Value | Description |
|---|---|
| direct | Get wholesale price by price and promotion_price. |
| by_sku | Get price by SKU. |
| by_volume | Get price by price_range and depends on minimum order quantity moq. |
Seller levels on 1688
The level is also used to determine seller credibility on 1688, determined through the seller_type field. There are 3 levels:
| Value | Description |
|---|---|
| seller | Regular seller. |
| merchant | Professional seller, verified by 1688. |
| factory | Manufacturing factory, verified by 1688 and meets 1688 direct evaluation standards. |
Explanation of field values in extra_info
| Value | Description |
|---|---|
| isOnePsale | Does it support dropshipping? |
| isSupportMix | Does it allow buying multiple products in one order? |
| isOnePsaleFreePostage | Does it support dropshipping + freeship? |
| noReason7DReturn | Does it allow no-reason return within 7 days? |
| 1688_yx | Is it a selected source? |