Order detail and list API

POST /v1/orders/detail {#detail}

{
  "channel": "1688",
  "order_id": "3304203601144335680"
}

Response: StandardOrderDetail. In warehouse mode, may include domestic_parcels[] for fulfillment create.

See order response models.

POST /v1/orders/list {#list}

Use one request format to list 1688, Taobao or Weidian buyer/procurement orders. A live key needs order:read, an enabled channel quota and valid buyer authorization for the current app. This operation only reads orders; it does not create, pay, cancel or record GMV.

{
  "channel": "taobao",
  "start_time": "2026-10-01 00:00:00",
  "end_time": "2026-10-12 23:59:59",
  "time_type": "updated",
  "timezone": "Asia/Shanghai",
  "page_no": 1,
  "page_size": 50,
  "response_format": "standard"
}

Change channel to 1688 or weidian to use the same date and pagination fields. Gateway converts them to each vendor’s native parameters.

Request fields

Channel capabilities and defaults

Taobao lists procurement orders visible to the authorized buyer/API, not every retail order in the buyer’s Taobao account. time_type: "created" on Taobao returns HTTP 400 UNSUPPORTED_TIME_FILTER, rather than silently substituting update time. Querying an update window and filtering created_time afterward is not a guaranteed complete creation-time history.

A valid request with no explicit time fields is also supported:

{
  "channel": "taobao",
  "page": 1,
  "page_size": 50,
  "response_format": "standard"
}

This returns the last 7 days of updated procurement orders, not an all-time export. When paginating a default window, use the returned query.start_time/query.end_time and timezone explicitly for subsequent pages to keep it fixed. Marketplace data can still change during pagination; deduplicate by order ID when synchronizing.

Standard response

All three channels return channel, page_no, page_size, total, has_next, orders and request_id. The legacy page field remains; Weidian also retains its 0-based page_num.

1688 rows retain their existing standard order model. Taobao and Weidian lists are lightweight: each row has a string order_id; Taobao also includes the external out_order_id and normalized/raw status when available. Use order detail for complete item, amount and logistics data.

If Taobao does not return results_total, total is null, not a guessed count. In that case, a full page sets has_next: true to suggest another page may exist. Weidian’s has_next respects its 10,000-record cap even when its reported total is larger.

For friendly ranges or Taobao’s default window, query contains the effective time_type, start_time, end_time, timezone and defaulted. A default window has defaulted: true. ID lookups/native ranges may omit this metadata. Standard list responses do not introduce new cross-channel monetary assumptions; fetch details for monetary fields.

Legacy parameters

Friendly start_created/end_created aliases select creation time only on 1688/Weidian; start_updated/end_updated aliases select update time on all three. Do not mix friendly field families, or mix friendly and native time fields. Legacy native fields are not reinterpreted through timezone; that parameter applies to friendly date strings.

Validation and upstream responses

Invalid/partial ranges, nonexistent dates, conflicting page aliases, invalid timezone, invalid response format and out-of-range pagination return HTTP 400 VALIDATION_ERROR before a vendor query. DST-gap or ambiguous wall times are rejected; use UTC with the correct equivalent date/time in these cases. Unsupported channels or Taobao creation-time requests have explicit 400 codes. Transport and upstream business failures remain 502; authorization/quota failures retain their existing 401/403/429 behavior.

response_format: "upstream" returns the vendor response envelope, including upstream_api, upstream and request_id; date conversion and validation still apply.

1688/Taobao Sandbox requests use existing fixtures, not real date filtering or a live buyer account. Weidian buyer lists and all upstream-format requests are unavailable in Sandbox.

POST /v1/orders/purchase/query {#purchase-query}

This compatibility endpoint now accepts the same three channels and request parameters as /v1/orders/list. It defaults to Taobao when channel is omitted. New integrations should prefer /v1/orders/list.

For Taobao standard responses, the existing vendor-shaped code/data/purchase_orders payload is retained so existing clients do not break; it is not renamed to orders. For 1688/Weidian, this endpoint returns the same list model as /list. Upstream format uses the usual vendor envelope for every channel.

To query a known Taobao ISV order without dates:

{
  "channel": "taobao",
  "outer_purchase_id": "YOUR_ISV_PURCHASE_ID"
}

OpenAPI: GET https://api.hiobuy.com/openapi.json.