Product API response models

With response_format: "standard" (default), product endpoints return the types below. Canonical TypeScript: packages/shared/src/products.ts.

Endpoints: detail · search · image search · parse

Monetary units {#monetary-units}

Response envelope {#envelope}

StandardProductDetail {#standard-product-detail}

Full product snapshot for product pages and checkout. Map to orders: search/detail id → lines[].id (offer_id / Taobao mi_id still accepted); variants[].sku_id → spec_id (Procurement orders).

Identity & channel

Localized text (title, description)

Pricing (price, price_tiers[])

All amounts CNY yuan (not fen). Prefer promotion_amount when set, else display_amount.

Media (images[], videos)

Attributes vs variants

Only variants[] drives SKU selection and order lines.

Variant object (variants[])

SKU package dimensions (variants[].shipping)

Mapped from 1688 upstream productShippingInfo.skuShippingDetails (SkuShippingDetail). Taobao has no equivalent — always null. Empty or 0 size/weight values normalize to null; if a SKU has no dimension data at all, shipping itself is null.

For freight estimates, prefer official_*, then merchant-declared size/weight, then ai_weight_kg (with ai_weight_accuracy as a confidence hint).

Seller, shipping & metadata

Example (truncated)

{
  "product": {
    "id": "554456348334",
    "channel": "1688",
    "source_product_id": "554456348334",
    "title": {
      "original": "...",
      "translated": "...",
      "language": "en"
    },
    "price": {
      "display_amount": 29.9,
      "promotion_amount": 24.9
    },
    "variants": [
      {
        "sku_id": "b266e0...",
        "upstream_sku_id": "12123313",
        "stock": 100,
        "shipping": {
          "width_cm": 10,
          "length_cm": 10,
          "height_cm": 10,
          "weight_kg": 1.2,
          "official_width_cm": 5,
          "official_length_cm": 12,
          "official_height_cm": 14,
          "official_weight_kg": 0.001,
          "ai_weight_kg": 0.001,
          "ai_weight_accuracy": "80%",
          "source": "商家自填"
        }
      }
    ]
  },
  "request_id": "req_..."
}

Channel field availability

StandardProductList {#standard-product-list}

From search and image search. Each items[] entry is a summary — call detail for SKU matrix.

StandardProductListItem

Upload-image response {#upload-image-response}

Variant selection {#variant-selection}

1. Load detail → read product.variants.
2. Group by attributes[].original_name for dimension pickers (or by prop_id when present).
3. Filter variants on each user choice; disable out-of-stock options.
4. Pass matching sku_id and source_product_id to order preview.

Matching keys: prefer prop_id + value_id (Taobao) when both are set — they are stable CPV identities and avoid cross-SKU name collisions (e.g. many options sharing Color Classification). Fall back to original_name + original_value for UI grouping. Use name / value for display only. Do not infer semantic types from labels.

{
  "prop_id": "1627207",
  "value_id": "43553464153",
  "name": "Color Classification",
  "value": "[Special for Bicycle Maintenance] Professional 46-Piece Set",
  "original_name": "颜色分类",
  "original_value": "【自行车维修专用】专业46件套",
  "image": "https://img.alicdn.com/..."
}

On 1688 the same shape is used with prop_id from attributeId and value_id: null (upstream SkuAttribute has no value id).