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

Response envelope {#envelope}

Endpoint	Shape
`detail`, `parse`	`{ product: StandardProductDetail, request_id }`
`search`, `search-by-image`	`StandardProductList & { request_id }`
`upload-image`	`{ channel, image_id, request_id }`

StandardProductDetail {#standard-product-detail}

Full product snapshot for product pages and checkout. Map to orders: source_product_id → offer_id, variants[].sku_id → spec_id (Procurement orders).

Identity & channel

Field	Type	Description
`id`	string	HIOBuy composite key: `{channel}_{source_product_id}`
`channel`	string	`1688`, `taobao`, or `weidian`
`source_product_id`	string	1688 = `offerId`; Taobao = `mi_id` (required for order APIs)
`source_url`	string	Canonical product page URL

Localized text (`title`, `description`)

Field	Type	Description
`original`	string	Marketplace text (typically Chinese)
`translated`	string \| null	Translation for requested `language`
`language`	string	Locale of `translated`
`description`	object \| null	Long-form detail (often HTML)

Pricing (`price`, `price_tiers[]`)

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

Field	Type	Description
`price.original_amount`	number	List price before promotions
`price.display_amount`	number	Buyer-facing price (CNY)
`price.promotion_amount`	number \| null	Promotional unit price when applicable
`price.original_currency` / `display_currency`	string	Always `CNY`
`price_tiers[]`	array	1688 wholesale breaks; empty on Taobao
`min_order_quantity`	number \| null	1688 MOQ
`distribution_min_quantity`	number \| null	1688 dropship minimum

Media (`images[]`, `videos`)

Field	Type	Description
`images[].url`	string	Image CDN URL
`images[].type`	enum	`main`, `gallery`, or `variant`
`videos.main` / `videos.detail`	string \| null	1688 videos; Taobao `null`

Attributes vs variants

Only variants[] drives SKU selection and order lines.

Field	Role
`attributes[]`	CPV specs — display only, not for SKU resolution
`variants[]`	Purchasable SKU matrix with price, stock, specs

Variant object (`variants[]`)

Field	Type	Description
`sku_id`	string	Pass as `spec_id` on order create
`upstream_sku_id`	string \| null	1688 numeric `skuId`
`attributes[]`	array	Spec dimensions (color, size, …)
`price`	object	SKU-level price in yuan
`stock`	number	Available qty; `0` = out of stock
`image`	string \| null	SKU primary image
`shipping`	object \| null	1688 package dimensions for freight
`distribution`	object \| null	1688 dropship pricing

Seller, shipping & metadata

Field	Type	Description
`seller.id` / `seller.name`	string	Shop id and display name
`seller.shop_url`	string \| null	Storefront link
`shipping.shipping_from`	string \| null	Domestic dispatch region
`shipping.domestic_shipping_fee`	object \| null	Estimated domestic fee in yuan
`metadata.raw_category`	string \| null	Upstream category
`metadata.brand`	string \| null	Declared brand
`metadata.updated_at`	string	ISO 8601 last sync
`trade_score`	string \| null	1688 quality score

Example (truncated)

{
  "product": {
    "id": "1688_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...",
        "stock": 100
      }
    ]
  },
  "request_id": "req_..."
}

Channel field availability

Field	1688	Taobao	Weidian
`videos`, `price_tiers`, `trade_score`	✓	—	Varies
`variants[].shipping`, `distribution`	✓	—	—
`source_product_id` for orders	`offerId`	`mi_id`	Platform id

StandardProductList {#standard-product-list}

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

Field	Type	Description
`channel`	string	Marketplace queried
`keyword`	string	Echo of keyword (empty for pure image search)
`page` / `page_size`	number	Pagination applied
`total`	number	Upstream total (may be approximate)
`items[]`	array	`StandardProductListItem` objects
`pic_region_info`	object	Image search: detected crop region

StandardProductListItem

Field	Type	Description
`id`, `channel`, `source_product_id`, `source_url`	string	Use `source_product_id` to fetch detail
`title`	LocalizedTitle	Listing title
`price`	ProductPrice	Summary price in CNY yuan
`image`	string	Thumbnail URL
`seller.name`	string	Shop name

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

Field	Type	Description
`channel`	string	Marketplace that stored the image
`image_id`	string	Reuse in image search

Variant selection {#variant-selection}

Load detail → read product.variants.
Group by attributes[].original_name for dimension pickers.
Filter variants on each user choice; disable out-of-stock options.
Pass matching sku_id and source_product_id to order preview.