Order API response models
Types in packages/shared/src/ (order-preview-result.ts, order-create-result.ts, trade.ts, logistics-trace.ts).
Standard responses on preview, create, and detail include top-level monetary_unit: "CNY_minor" — all { amount, currency } values are CNY fen (1 yuan = 100 fen). POST /v1/products/freight/estimate uses the same convention. Product catalog prices use yuan (CNY_major); see Product response models. Upstream format omits monetary_unit.
StandardOrderPreviewResult {#standard-order-preview-result}
From order preview.
| Field | Type | Description |
|---|---|---|
success | boolean | true only when the payable total, seller groups, requested lines, availability, and applicable trade mode pass validation |
total.merchandise | Money | null | Merchandise subtotal; null only when genuinely unknown |
total.payment | Money | Total payable |
total.shipping | Money | null | Domestic shipping portion; known free shipping is Money with amount: 0 |
sellers[] | array | Grouped by seller with lines[], fees |
unavailable_lines[] | array | Failed validation or stock |
trade_types[] | array | 1688 only |
promotions | object | 1688 promotions when present |
code / message | string | Optional business status, including LINE_UNAVAILABLE, UNSUPPORTED_TRADE_MODE, or PREVIEW_INCOMPLETE |
monetary_unit | string | Always CNY_minor in standard preview responses |
request_id | string | Request correlation id |
A parseable but incomplete standard preview is HTTP 200 with success:false. Existing 1688 upstream SKU, stock, MOQ, and marketplace business errors retain the legacy HTTP 502 CHANNEL_UPSTREAM_ERROR behavior for compatibility. In response_format:"upstream", HTTP 200 can contain an upstream business failure; inspect the raw upstream.success, code, message, and nested equivalents.
StandardOrderCreateResult {#standard-order-create-result}
| Field | Type | Description |
|---|---|---|
order_id | string | Use for pay, detail, trace |
total.payment | Money | Amount to pay |
order_list[] | array | Sub-orders / seller splits |
failed_offers[] | array | Partial create possible with success: true |
outer_purchase_id | string | Taobao idempotency key |
payment_url | string | Taobao optional payment URL |
StandardOrderPayResult {#standard-order-pay-result}
| Field | Description |
|---|---|
success | Channel payment result. Taobao self standard mode: true only after order query confirms payment |
pending / payment_status | Optional Taobao self confirmation fields. Pending/unknown is not a confirmed failure; do not submit a new payment |
order_status / order_status_raw | Latest normalized/official order status used for Taobao confirmation |
upstream_request_id | Official payment API request id, when supplied |
payment_submission_status | Optional Taobao self evidence: submitted, rejected, unknown; not settlement status |
payment_recovery | Optional action, reason, elapsed_seconds; see payment recovery. Manual review is not automatic retry permission; elapsed time is from the original keyed attempt |
pay_channel | 1688 payment method |
error_code / error_message | Explicit payment rejection; may be absent for pending/unknown |
StandardOrderDetail {#standard-order-detail}
| Field | Description |
|---|---|
status | e.g. wait_payment, wait_shipment, shipped |
refund_status | Read-only; refund APIs not public |
amounts | total, product_total, shipping_fee, refund (fen) |
line_items[] | Product rows with sku_specs, status |
times | created_at, paid_at, shipped_at, … |
domestic_parcels[] | Warehouse mode → fulfillment |
UnifiedLogisticsTrace {#unified-logistics-trace}
From domestic trace.
| Field | Description |
|---|---|
packages[] | tracking_number, carrier, steps[] |
cross_border_packages[] | 1688 cross-border nodes — not international fulfillment |
StandardOrderCancelResult {#standard-order-cancel-result}
| Field | Description |
|---|---|
success | Cancel accepted (may still process) |
pending | Taobao async cancel |
sub_order_ids | Partial cancel affected ids |
Get Support
Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days