# Taobao Product details API (taobao.product_detail)

- Canonical page: https://everyinfra.com/en/taobao-api/product_detail
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "taobao", "action": "product_detail", "params": {...}}
- Price: $0.0045 per call ($4.5 per 1,000 requests); failed calls and empty results are not charged
- Returns: single object
- Mode: sync; add "mode": "async" for slow tasks

Taobao Product details reads the full public record of one Taobao or Tmall product: title, brand, price and original price, the coupon price, stock and units sold, every SKU with its own price and stock, product attributes, the main image and long description images, plus the shop and shipping fees. Use it to take a competitor's listing apart, track prices and promotions, compare offers or fill in a product catalog. Only part of the calls return brand, original price, coupon price, units sold, product attributes, shop ID and shipping fees, so a missing value does not always mean the product lacks it.

`url` takes a numeric product ID, a product link or share text that contains exactly one product link; bare Taobao share codes and expired links are rejected. When reading prices, note that `coupon_price` appears only when a coupon applies and that each entry in `skus` can carry its own price. `is_tmall` separates Tmall stores from regular Taobao shops, which come with different requirements and guarantees.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=taobao&action=product_detail

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| url | not declared | yes | not declared | For product_detail, reviews, or questions, use a numeric item ID, a Taobao/Tmall product URL, or a share message containing exactly one product URL. e.tb.cn and m.tb.cn links work only when they can be safely resolved to a product page. TaoPassword-only tokens, expired links, and non-product pages are rejected. A sync call takes at most about 85 seconds; set your client timeout to at least 95 seconds. For product_detail, when the item has been taken down or does not exist, the result is empty with empty_reason item_not_found and nothing is charged. |

## Response fields (items in `results`)

| 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). |
| brand | Brand. |
| price | Price as a number without a currency symbol; see currency. In product_detail, prices (including each skus row's price) are either the CNY price shown on the Taobao page or a CNY price converted from US dollars, which can be about 1–4% above or below the page price; the page price is authoritative. In search, each row's price can be the current page price, the struck-through list price or a promotion price. price_basis says which kind you got. |
| original_price | Original (struck-through) price. In product_detail it is empty on most calls. In shop it is the only price: the struck-through figure the listing shows, not the selling price, and it can be well above it; use product_detail for the selling price. |
| currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
| price_basis | How price was obtained (present only when there is a price). In product_detail: page is the CNY price shown on the Taobao page; converted is a CNY price converted from US dollars and can be about 1–4% above or below the price on the Taobao page. In search (one per row): page is the current price shown on the Taobao page; list is the struck-through list price, which is above the actual selling price when the item is discounted, sometimes twice as much; promotion is a Taobao affiliate promotion price and is often well below the page price. currency is CNY in every case, and calls for the same product can differ. |
| stock | Stock count. For sellers with several warehouses, calls for the same product can return different stock (and a different ship-from location). In product_detail, when the source gives no stock for the whole product, this is the sum of the SKU stocks. |
| sold_count | Units sold. In product_detail only part of the calls return it, and that share changes from day to day. |
| category_id | Category ID. |
| location | Ship-from location. For sellers with several warehouses, calls for the same product can show different ship-from locations. |
| is_tmall | Whether the store is a Tmall store, as opposed to a regular Taobao shop; the two have different entry requirements and buyer guarantees. In product_detail, some sources do not return it. |
| shop_name | Shop name. |
| shop_id | Shop ID. |
| shipping_fee | Shipping fee. In product_detail it is empty on most calls. |
| ems_fee | EMS shipping fee. In product_detail it is empty on most calls. |
| express_fee | Express delivery fee. In product_detail it is empty on most calls. |
| skus | Every variant (SKU) of the listing. Each entry can carry id, name, price, original_price, coupon_price, stock, props_ids and image_url; price can be a converted price (see price). |
| sku_count | Number of SKUs. |
| spec_values | Full table of variant values, including combinations not on sale; id identifies the value and text is its label. |
| props_images | Images for variant values: id matches spec_values and props_ids, and image_url is that variant's display image. |
| attributes | Product attributes as {name, value} rows, such as brand, model and place of origin. |
| main_image_url | Main (first) image. For product detail (product_detail), a call that returns neither this nor `images` is not charged; the other fields still come back. |
| description_images | Long images in the description area, in page order. In product_detail it is empty on some calls. |
| description_html | Raw HTML of the description area, mostly image tags. In product_detail it is empty on some calls. |
| video_url | Direct link to the main-image video. This field is usually empty because the video is rarely available; an empty value does not mean the product has no video. |
| coupon_price | Price after coupon: lower than price when a coupon applies, absent otherwise. In product_detail only part of the calls return it (that share changes from day to day), so a missing value does not always mean there is no coupon. |
| price_usd | Reference price in US dollars, as converted in the returned data. In product_detail it is empty on most calls. |
| total_price | Total price as returned; often absent. |
| suggestive_price | Suggested retail price; often absent. |
| has_discount | Whether a discount applies. In product_detail it is empty on most calls. |
| is_promotion | Whether the product is on promotion. In product_detail it is empty on most calls. |
| promo_type | Promotion type. |
| is_virtual | Whether the product is virtual (not a physical good). In product_detail it is empty on most calls. |
| brand_id | Brand ID. |
| root_category_id | Root category ID. |
| category_path | Category path (breadcrumb). |
| weight | Product weight as returned; often 0 or absent. In product_detail it is empty on most calls. |
| size | Product dimensions; often absent. |
| favorite_count | Number of times the product was added to favorites. |
| fans_count | Follower count as returned; often absent. |
| min_order_quantity | Minimum order quantity. In product_detail it is empty on most calls. |
| shipping_to | Delivery area note; often absent. |
| listed_at | Listing time (ISO 8601); the field is absent when the data has none. |
| modified_at | Last modified time (ISO 8601); the field is absent when the data has none. |
| delist_at | Delisting time (ISO 8601); the field is absent when the data has none. |
| images | Image links: product photos on product_detail, the buyer's photos on reviews (absent when the review has none). |
| category_name | Leaf category name (product_detail). |
| description | Summary or description, usually shorter than text. |
| keywords | Keywords from the product page (product_detail). |
| titleOriginal | platform-native meaning |
| has_cn_title | platform-native meaning |
| shop_score_description | Shop rating for item-as-described, on a 5-point scale. |
| shop_score_service | Shop rating for service, on a 5-point scale. |
| shop_score_delivery | Shop rating for delivery, on a 5-point scale. |
| free_shipping | Whether shipping is free. |
| promotion_price | Promotional price (product_detail; often missing). |
| discount_price | Discounted price (product_detail; often missing). |
| discount_type | Discount or campaign type as written (for example flash sale). |
| price_note | Price note as written (product_detail). |
| has_price_range | Whether the price is a range because variants cost different amounts (product_detail). |
| payment_methods | Accepted payment methods (product_detail). |
| seller_id | Seller ID (can be missing in shop; in product_detail, some sources do not return it). |
| seller_credit_level | Seller credit level (a number; higher is better). |
| seller_type | Seller type code (product_detail). |
| seller_type_label | Seller type name (product_detail), for example Tmall or business shop. |
| selling_points | Selling-point tags. |
| shop_logo_url | Shop logo link (product_detail, shop; can be missing in shop). |
| shop_url | Shop link (product_detail, shop). |
| shop_item_count | Number of items on sale in the shop (product_detail, search, shop). |
| shop_new_item_count | Number of new items in the shop (product_detail). |
| shop_opened_at | When the shop opened, as written (product_detail). |
| review_tags | Review tags, each with tag (the label) and count (how often it was mentioned; may be missing). |
| review_count | Number of reviews, for product and business capabilities. null means not disclosed, not 0. |
| positive_rate | Product positive-review rate (product_detail), as a percentage; often missing. |
| seven_day_return | Whether seven-day no-reason returns are supported (product_detail). |
| reviews | platform-native meaning |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "taobao",
  "action": "product_detail",
  "params": {
    "url": "https://item.taobao.com/item.htm?id=744983869996"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "taobao",
        "action": "product_detail",
        "params": {
            "url": "https://item.taobao.com/item.htm?id=744983869996",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-10-24T18:28:34Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "taobao",
  "action": "product_detail",
  "results": {
    "id": "•••",
    "url": "https://item.taobao.com/item.htm?id=744983869996",
    "title": "绿联转换插头英标韩国马来西亚澳洲新加坡新西兰Switch转换器充电",
    "price": 29.97,
    "currency": "CNY",
    "stock": 1397,
    "category_id": "50003472",
    "location": "廣東東莞",
    "is_tmall": true,
    "shop_name": "绿联数码旗舰店",
    "shop_id": "67095450",
    "skus": [
      {
        "id": "•••",
        "name": "[for Outings] English to Chinese Converter|Matte Black⭐Applicable to Hong Kong/Macau/Malaysia/Singapore, China",
        "price": 30.17,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i3/713464357/O1CN01QOFAISCEu2L1chua_!!713464357.jpg"
      },
      {
        "id": "•••",
        "name": "[for Outings] English to Chinese Converter|Lightweight White⭐Applicable to Hong Kong/Macau/Malaysia/Singapore, China",
        "price": 29.97,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01P9gIa5t80pC1chua_!!713464357.jpg"
      },
      {
        "id": "•••",
        "name": "[for Mainland China] Chinese to English Converter|Matte Black⭐Applicable to Hong Kong Version of Ps5/Switch2/Electrical Appliances in Hong Kong and Macau, China",
        "price": 30.17,
        "stock": 200,
        "image_url": "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01WLbh5e1i3YjKWsf7g_!!713464357.jpg"
      }
    ],
    "sku_count": 8,
    "main_image_url": "https://img.alicdn.com/bao/uploaded/i4/713464357/O1CN01Cr4DMB1i3YoKXb4bM_!!4611686018427386405-0-item_pic.jpg",
    "description_images": [
      "https://img.alicdn.com/imgextra/i1/713464357/O1CN01tRpmSz1MdQI1WPZ8_!!713464357.jpg",
      "https://img.alicdn.com/imgextra/i1/713464357/O1CN019muBmB1i3YpL3L8sM_!!713464357.jpg",
      "https://img.alicdn.com/imgextra/i3/713464357/O1CN011J4LMz1i3Ynq3SQ1z_!!713464357.jpg"
    ],
    "price_usd": 5.27,
    "root_category_id": "50020579",
    "category_path": "首页 > 电子/电工 > 接线板/插头 > 转换插头",
    "min_order_quantity": 1,
    "images": [
      "https://img.alicdn.com/bao/uploaded/i4/713464357/O1CN01Cr4DMB1i3YoKXb4bM_!!4611686018427386405-0-item_pic.jpg",
      "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01f4WmsN1i3YoKlcotr_!!713464357.jpg",
      "https://img.alicdn.com/bao/uploaded/i2/713464357/O1CN01KQ3NjW1i3YljOLkIv_!!713464357.jpg"
    ],
    "category_name": "转换插头",
    "description": "港版Switch转换插头 - 英标转中转换器，适用马来西亚插头与多国转换插头，具备65W快充功能。适合港版Switch 1与2使用，提供全球适用的转换解决方案。\n\n多国适用与高效快充功能 - 绿联多国转换插头支援英标、美标、德标与澳标等多种插头类型，适用全球多数国家与地区。内建65W快充技术，确保高功率需求的装置如Switch主机与笔电能快速充电，同时具备安全保护机制，避免过载与短路。\n\n多样款式与便利设计选择 - 转换插头提供多种款式选择，包含单独英转中、中转英与多合一组合。特别针对港版Switch 2使用者设计，提供适用进口电器的转换方案。轻巧便携设…",
    "keywords": [
      "港版Switch转换插头",
      "英标转中转换器",
      "适用马来西亚插头"
    ],
    "shop_score_description": 4.8,
    "shop_score_service": 4.8,
    "shop_score_delivery": 4.9,
    "free_shipping": false,
    "has_price_range": true,
    "payment_methods": [
      "蚂蚁花呗",
      "信用卡支付",
      "集分宝"
    ],
    "seller_id": "•••",
    "seller_credit_level": 20,
    "seller_type": "B",
    "seller_type_label": "Business seller",
    "selling_points": [
      "港版Switch2转换插头:专为港版Switch2设计转换插头，兼容多国电压，出国携带无烦恼。",
      "绿联品牌认证转换器:知名电子品牌绿联出品，通过多国安全认证，使用更安心。",
      "多国插头规格适用:适用马来西亚、新加坡、英国等多国插座标准，国际旅行首选。"
    ],
    "shop_logo_url": "https://img.alicdn.com/imgextra//d2/82/TB1rBsXkkL0gK0jSZFASuwA9pXa.jpg",
    "shop_url": "https://shop.m.taobao.com/shop/shop_index.htm?user_id=713464357",
    "shop_item_count": 1330,
    "shop_new_item_count": 28,
    "shop_opened_at": "2011-05-30 14:37:22",
    "seven_day_return": false,
    "reviews": [
      {
        "text": "还不错，通电了装换头会有提示灯 没送收纳袋。 体积挺小巧的。 手感挺细腻的。",
        "rating": 5,
        "posted_at": "2026.10.17 18:07",
        "sku": "颜色:【内地用】中转英转换器|轻骑白⭐港版PS5/Switch2/中国香港澳门地区电器适用",
        "author_avatar_url": "https://gw.alicdn.com/•••"
      }
    ],
    "platform": "taobao"
  },
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### What can I pass as `url`?

A numeric product ID, a Taobao or Tmall product link, or share text that contains exactly one product link. Short links from e.tb.cn and m.tb.cn are accepted only when they resolve safely to a product page. Bare share codes, expired links and shop or search pages are rejected.

### How do I read prices for products with several variants?

`skus` lists every variant, and each can carry its own price, original price, coupon price and stock, while `price` is the product-level figure. Record prices per variant when you compare or monitor them; `spec_values` adds every variant value, including combinations not on sale.

### Are prices in yuan, and is there a US dollar figure?

`price`, `original_price` and `coupon_price` are plain numbers without a currency symbol, so read the currency from `currency` instead of assuming it. `price_usd` is a reference price in US dollars, as converted in the returned data; it is empty on most calls, and when present it is for rough comparisons, not the amount you will pay. The yuan prices in product details are either the price shown on the Taobao page or a price converted from US dollars, which can be about 1–4% above or below the page price; `price_basis` says which one you got, and the page price is authoritative.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=taobao
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
