نماذج استجابة Fulfillment API
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".
Freight estimate — quotes[] {#freight-estimate-quotes}
| Field | Description |
|---|---|
shipping_channel_code | Pass to create |
shipping_channel_name / description | Localized copy (language in body) |
freight / total | Indicative — binding on create |
estimated_days_min / max | Transit range when provided |
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 idempotency key from create; 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 idempotency key from create; 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 may be null |
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, title, occurred_at }. Empty code → null |
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 timeline is business events (packed / paid). Scan events stay on international tracking.
Balance {#balance}
| Field | Description |
|---|---|
balance.available | Spendable for pay |
balance.frozen | Held for pending shipments |
balance.total | Available + frozen |
International trace — events[] {#international-trace-events}
| Field | Description |
|---|---|
status | pending, in_transit, customs, delivered, exception |
events[].description | Carrier scan text |
tracking_number | Line-haul / last-mile number |
These are carrier scan events. Warehouse business events (CREATED / packed / paid) live on shipment detail timeline[], not here.
Get Support
Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days