Fulfillment API response models
Standard responses (response_format omitted or "standard") include a top-level field:
| Field | Value | Meaning |
|---|---|---|
monetary_unit | "CNY_minor" | Every { amount, currency } in the response uses CNY fen (minor unit); 1 yuan = 100 fen |
Present on money-bearing routes: balance, freight estimate, create, cancel (with refund), list, detail, services. Omitted on pay, logistics trace, item-attributes, and on response_format: "upstream".
Versandangebote — quotes[] {#freight-estimate-quotes}
Vollständige Anfrage/Antwort: Versandangebote. Kanalkatalog: Versandkanäle. Die Anzeigesprache ist der Header Language, kein Feld im Body oder in der Query.
| Feld | Beschreibung |
|---|---|
channel.code / name / description / tags | Stabile Kanalidentität. Beim Erstellen code verwenden, nicht name |
available / quote_status | Immer beide lesen. UNAVAILABLE ist ein Angebotsergebnis, kein HTTP-Fehler |
unavailable_reason | { code, message } oder null. code ist programmatisch |
matched_region | { code, name, match_type } |
packages / weights | Deklarierte Pakete; actual / volumetric / chargeable in KG |
billing_quantity / pricing_selector | Menge und Einheit, die der Kanal abrechnet (KG / M3 / KG_PER_M3) |
transit_time | Referenzlaufzeit |
charges | base_freight / channel_services / channel_rules / outbound_services / inbound_services / adjustments |
display_charges | Nur-UI-Zeilen; überspringen, wenn included_in_total false ist |
total / known_total | Vollständiges Budget vs. derzeit bekannte Gebühren. known_total nicht als vollständig behandeln, wenn total null ist |
service_adjustment_possible | Die Lagerbearbeitung kann Dienste und Gebühren noch ändern |
monetary_unit | Immer CNY_minor |
Preview / create — pricing {#preview-create-pricing}
| Field | Description |
|---|---|
freight | International line-haul |
services | Value-added services total |
discount | Promotional deduction |
total / total.payment | freight + services − discount |
id / order_sn | Create: Public id is warehouse numeric PK as a string; order_sn is the warehouse order number |
status | PENDING, WAIT_PAYMENT, WAIT_SHIP, SHIPPED, SIGNED, CANCELLED |
Shipment list {#shipment-list}
GET /v1/fulfillment/shipments returns lightweight rows. Example: Shipments · list.
| Field | Description |
|---|---|
id / order_sn | Public id is warehouse numeric PK as a string; order_sn is the warehouse order number |
external_shipment_id | ISV business/reconciliation id from create; not the Idempotency-Key retry header; empty warehouse string → null |
status | PENDING / WAIT_PAYMENT / WAIT_SHIP / SHIPPED / SIGNED / CANCELLED |
international_tracking | { tracking_number, carrier }. No top-level tracking_number |
receiver / shipping_channel / services[] | Same shape as detail |
total | Detail-style charges / discount / payable / paid / outstanding |
payment_status | UNPAID / PAID / PARTIAL |
times | created_at / packed_at / paid_at / shipped_at / delivered_at / cancelled_at |
pagination | page / page_size / total / total_pages |
List omits boxes, timeline, files, charges, shipping_legs, source_packages, and interception.
Shipment detail {#shipment-detail}
GET /v1/fulfillment/shipments/{id} is the full shipment view. Create / pay still use summary total.freight / services / discount / payment. Amounts are fen. Example: Shipments · detail.
| Field | Description |
|---|---|
id / order_sn | Public id (path param) is warehouse numeric PK as a string; order_sn is the warehouse order number |
external_shipment_id | ISV business/reconciliation id from create; not the Idempotency-Key retry header; empty warehouse string → null |
status | PENDING / WAIT_PAYMENT / WAIT_SHIP / SHIPPED / SIGNED / CANCELLED |
source_packages[] | Inbound domestic packages (id may be null in a transition payload) |
receiver | International recipient; country_code is uppercase ISO; district / personal_code may be null. personal_code is the optional personal customs clearance code (e.g. Korea PCCC) from create |
shipping_channel | { code, name } |
multi_box | true when boxes.length > 1 |
boxes[] | Outbound cartons: box_no (warehouse box_sn), source_package_ids (warehouse package_ids), weight / dimensions, optional tracking |
international_tracking | { tracking_number, carrier }; empty warehouse strings → null |
timeline[] | Warehouse business events { code, status, title, occurred_at, details }; code is stable and non-null; details is {} when empty; newest first |
shipping_legs[] | FIRST_MILE / LAST_MILE when numbers exist; otherwise [] |
files[] | PACKING_IMAGE / PACKING_VIDEO |
services[] | VAS on this shipment (service_code, name, quantity, status) |
charges[] | Line items. Discount rows are negative |
total | charges (positive fees) / discount (positive) / payable / paid / outstanding |
payment_status | UNPAID / PAID / PARTIAL |
times | created_at / packed_at / paid_at / shipped_at / delivered_at / …; unused = null |
charges[].type: FREIGHT, VALUE_ADDED_SERVICE, CHANNEL_SERVICE_FEE, CHANNEL_RULE_FEE, INSURANCE, DUTIES_AND_TAXES, PACKAGE_SERVICE, COUPON_DISCOUNT, POINTS_DISCOUNT.
Tracking numbers live on international_tracking / boxes[].tracking / shipping_legs. Warehouse business events (packed / paid) live on shipment detail timeline[]. Carrier scan nodes live on international tracking timeline[] (same { code, status, title, occurred_at, details } shape).
Balance {#balance}
| Field | Description |
|---|---|
balance.available | Spendable for pay |
balance.frozen | Held for pending shipments |
balance.total | Available + frozen |
International trace {#international-trace}
Subset of shipment detail — carrier scan nodes only.
| Field | Description |
|---|---|
id / order_sn | Same as detail |
shipping_channel | { code, name } |
international_tracking | { tracking_number, carrier }; empty warehouse strings → null |
status | PENDING / WAIT_PAYMENT / WAIT_SHIP / SHIPPED / SIGNED / CANCELLED |
status_label | Display copy from warehouse |
interception | Independent interception request state, or null; it does not replace shipment status |
timeline[] | { code, status, title, occurred_at, details }; code is stable and non-null; title is localized display copy; timezone-aware ISO 8601; newest first |
Detail timeline[] = warehouse business events. This route timeline[] = carrier scan events. Do not mix the two.
Get Support
Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days