Response format

HIOBuy Public API supports two response shapes on selected POST routes. Pass optional response_format in the JSON body.

At a glance

Default is standard. Omit response_format or set "response_format": "standard".

	`standard` (recommended)	`upstream`
What you get	HIOBuy unified models — same JSON shape across channels	Raw JSON from the upstream provider (1688 Open API, Taobao IOP, …)
Field mapping	Done by HIOBuy Gateway (names, nesting, units)	None — fields match the vendor’s official docs
1688 vs Taobao	One interface → one structure; switch `channel` without rewriting parsers	Each channel returns different vendor JSON
When to use	Production integrations, multi-channel apps	Debug against vendor docs, legacy migration
How to request	Default — no extra field needed	`"response_format": "upstream"`

Recommendation: Integrate against standard. HIOBuy maintains cross-channel compatibility in unified models. Use upstream only when you intentionally need the vendor’s native payload.

Auth, channel OAuth, quotas, and rate limits are the same for both modes.

Modes

Value	Description
`standard` (default)	Normalized HIOBuy types — same request, same response shape whether `channel` is `1688` or `taobao`.
`upstream`	Provider passthrough — official 1688 / Taobao JSON returned in `upstream` without HIOBuy field mapping.

Upstream envelope

When response_format is upstream:

{
  "channel": "1688",
  "response_format": "upstream",
  "upstream_api": "com.alibaba.fenxiao.crossborder/product.search.keywordQuery",
  "upstream": {
    "result": {
      "success": true
    }
  },
  "upstream_steps": [],
  "request_id": "req_abc123"
}

upstream_api — primary vendor API identifier (1688 path or Taobao IOP route)
upstream — raw HTTP JSON body from that call
upstream_steps — optional prior calls (e.g. image upload before image search)

Standard preview response {#standard-preview}

POST /v1/orders/preview (1688 and Taobao) returns StandardOrderPreviewResult in standard mode. Amounts are in fen (CNY cents). Field reference: Procurement orders.

{
  "channel": "taobao",
  "success": true,
  "total": {
    "payment": {
      "amount": 12900,
      "currency": "CNY"
    },
    "shipping": {
      "amount": 0,
      "currency": "CNY"
    }
  },
  "unavailable_lines": [],
  "sellers": [
    {
      "seller_id": "...",
      "lines": [
        {
          "offer_id": "...",
          "spec_id": "...",
          "quantity": 5
        }
      ]
    }
  ],
  "request_id": "req_..."
}

1688 adds trade_types, pay_channels, and promotions. With response_format: "upstream", preview returns raw vendor JSON instead.

Product routes

Endpoint	Channels	Upstream API (examples)
`POST /v1/products/detail`	1688, taobao	`queryProductDetail` / `/traffic/item/get`
`POST /v1/products/search`	1688, taobao	`keywordQuery` / `/traffic/item/search`
`POST /v1/products/search-by-image`	1688, taobao	upload + `imageQuery` / upload + `/traffic/item/imgsearch`

POST /v1/products/parse always returns standard only. POST /v1/products/freight/estimate uses the same body as order preview and returns shipping only.

Order routes (1688 & Taobao)

Endpoint	Standard	Upstream API (examples)
`POST /v1/orders/list`	✓	`alibaba.trade.getBuyerOrderList`
`POST /v1/orders/1688/preview`	✓	`alibaba.createOrder.preview`
`POST /v1/orders/1688/create`	✓	`alibaba.trade.createCrossOrder`
`POST /v1/orders/preview`	✓	Dispatches by `channel` (1688 / taobao)
`POST /v1/orders/create`	✓	Dispatches by `channel`
`POST /v1/orders/taobao/preview`	✓	`/purchase/order/render`
`POST /v1/orders/taobao/create`	✓	`/purchase/order/create`
`POST /v1/orders/cancel`	✓	`alibaba.trade.cancel`
`POST /v1/orders/pay`	✓	Dispatches by `channel`
`POST /v1/orders/detail`	✓	Order detail by `order_id`
`POST /v1/orders/logistics/trace`	✓	Domestic logistics trace
`POST /v1/orders/purchase/query`	✓	Taobao purchase list

Example — upstream search

curl https://api.hiobuy.com/v1/products/search \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "response_format": "upstream",
    "channel": "1688",
    "keyword": "phone case",
    "page": 1,
    "page_size": 10,
    "language": "en"
  }'

Validation

Invalid values (e.g. vendor_raw) return HTTP 400 with VALIDATION_ERROR. See Errors.

OpenAPI

Machine-readable spec: openapi.json (schemas UpstreamApiResponse, UpstreamStep).

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support