Product API v1 Reference (Legacy)
⚠️ Legacy: The v1 API will only run in parallel for a short time. New integrations should use the Product API v2.
Summary
This page lists the complete parameters and values of the product API v1: keyword search, image search, and product details on Taobao and 1688. For a step-by-step walkthrough, see Searching for products.
Search products by keyword
View details: Search products
POST /v1/products/search
Language translation (lang)
| 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 results (sort)
| 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 results (filter)
| 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 |
ffm_outbound values
| 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% |
ffm_delivery values
| Value | Description |
|---|---|
| FFMD0 | Same day delivery |
| FFMD1 | Delivery within 24h |
| FFMD2 | Delivery within 48h |
new_arrival values
| Value | Description |
|---|---|
| 7DAY | Newly updated products in the last 7 days |
| 30DAY | Newly updated products in the last 30 days |
seller_level values
| 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
POST /v1/products/search-img
There are 2 ways to search by image:
1. Search by image URL — Scope: ✅ Taobao ✅ 1688
Use the img_url key in the query parameter. Only image links from Alibaba can be used: *.alicdn.com
2. Search by uploaded image — Scope: ✅ Taobao ✅ 1688
First upload the image to Alibaba’s server using the API Upload image. Then use the img_id key instead of img_url in the query parameter.
Get detailed product information
View details: Product details
POST /v1/products/find
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.
Product price types
| Price Attribute | Description | Platform |
|---|---|---|
| price | Regular price. For 1688, 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. Depends on whether the seller has dropship active. | ❌ Taobao ✅ 1688 |
Price display and application logic
Some products may have multiple price types. Display and application logic depends on the platform. API prices may be higher than prices viewed directly on Taobao/1688 websites because website price mechanisms may have applied promotions, discounts, or other promotional programs that the API cannot apply.
Warning: If you display prices to customers on an extension/web/app, add a warning that prices may be higher than those viewed directly on Taobao/1688. If you find API prices are higher, contact customer service for help adjusting prices when creating purchase orders.
Taobao: prioritize displaying and applying the promotion price; if none exists, use the regular price.
1688: price application logic depends on 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, depends on minimum order quantity moq. |
Seller levels on 1688
Seller level is used to determine 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 meeting 1688 direct evaluation standards. |
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? |
Related links
- Current version: Product API v2
- How-to: Searching for products
- Tools: Elim CLI — search products from the terminal
- Full API reference: openapi.elim.asia/api