Product API Reference (v2)

Summary

This page lists the complete endpoints, parameters, and response structure of the Product API v2 (current version, recommended for new integrations): keyword search, image search, product details, image upload, and shipping fee calculation on Taobao and 1688.

If you are using the v1 version, see Product API v1 (Legacy). For a step-by-step walkthrough, see Searching for products.

All endpoints are POST, require an authentication header (JWT or API Key), and require the platform parameter with the value taobao or alibaba.

Search products by keyword

POST /v2/products/search

Example request:

{
  "platform": "taobao",
  "q": "áo thun cotton",
  "lang": "vi",
  "sort": "SALE_QTY_DESC",
  "page": 1,
  "size": 20,
  "filter": {
    "priceRange": { "min": 0, "max": 100 }
  }
}

Parameters

Sort results (sort)

Filter results (filter)

ffmOutbound values

ffmDelivery values

newArrival values

sellerLevel values

Search products by image

Note: This feature does not apply to the Free plan.

POST /v2/products/search-by-image

There are 2 ways to search by image; you must pass exactly one of the following parameters:

1. Search by image URL — use the imgUrl parameter

Only image links from Alibaba can be used: *.alicdn.com.

{
  "platform": "taobao",
  "imgUrl": "https://img.alicdn.com/bao/uploaded/i3/694223667/O1CN01zSjKgp1cxXRQZsDLA_!!694223667.jpg",
  "lang": "vi",
  "page": 1,
  "size": 20
}

2. Search by uploaded image — use the imgId parameter

First upload the image via the Upload image API to get an imageId, then pass it to imgId:

{
  "platform": "alibaba",
  "imgId": "image-123",
  "lang": "vi",
  "page": 1,
  "size": 20
}

Parameters

* At least one of imgUrl or imgId is required.

Get detailed product information

POST /v2/products/find
POST /v2/products/detail

Both endpoints share the same request structure and return detailed product information. detail returns fuller details and is suitable when you need 1688 data.

{
  "platform": "taobao",
  "id": "734467086498",
  "lang": "vi"
}

Parameters

If you encounter short links like https://e.tb.cn/h.hPY04k4RPfAco8F?tk=0CCI430IUqd, you must first process the link to get the original link — use the Unshorten link API to get the original link and product ID.

Product price types

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:

Seller levels on 1688

Seller level is used to determine credibility on 1688, determined through the seller_type field:

Field values in extra_info

Calculate shipping fee

Taobao only.

POST /v2/products/shipping-fee

{
  "platform": "taobao",
  "id": "734467086498",
  "addressInfo": {
    "country": "VN",
    "state": "Hanoi",
    "city": "Hanoi",
    "district": "Hoan Kiem"
  }
}

Parameters

The response contains post_fee (shipping fee in CNY), currency, item_id, mi_id, and item_resource.

Upload image

Used to get an imageId for image search (the imgId parameter).

POST /v2/products/upload-image

The request uses multipart/form-data:

Response: { "imageId": "image-123" }.

Response structure

Response field names use snake_case. Each platform returns its own product structure:

• find / detail → a product object (Product)
• search / search-by-image → { "paginate": { "total", "current", "size" }, "items": [...] } (the paginate key may be absent when there is no pagination metadata)

Core fields (present on both platforms)

1688-only fields

In addition to the core fields, a 1688 response adds the following fields (grouped by topic):

• Pricing: price_range, channel_price, promotion_model, fenxiao_sale_info, is_jxhy
• Media: video_urls, white_image, translated_img_urls, translated_white_image
• Translation: description_en, unit_en
• Sales/reviews: sold, review, level
• Shipping: shipping_info
• Category: top_category_id, second_category_id, third_category_id
• Identifiers & links: mp_id, item_type, batch_number, product_cargo_number, original_product_url, seller_shop_url, promotion_url
• Metadata: selling_point, offer_identities, create_date, is_select, certificate_list, seller_mix_setting
• Other: extra_info, sku_price_ranges

Note: A field entirely absent from the response means the field does not belong to the platform you are calling. A field with a null value means there is no data for that field in this request.

For the complete field list and detailed descriptions: Swagger API.

FAQ

Why is the product price from the API different from the price shown on the Taobao/1688 website?

1. The API we are using is part of Alibaba’s cross-border logistics system, and its pricing is determined independently — separate from the prices shown on the website.
2. Unlike the API, the website can distinguish between new and returning visitors, which allows it to apply targeted promotions or vouchers based on user type — a capability the API does not support.

Is there a test environment?

No. The default account already includes 200 free requests for trial integration.

Is the data real-time?

Yes, the data is retrieved directly from Taobao and 1688.

Do you support image search?

Yes, we support searching by image URL and uploaded image.

Related links

• How-to: Searching for products
• Legacy: Product API v1 (Legacy)
• Tools: Elim CLI — search products from the terminal
• Full API reference: openapi.elim.asia/api