International fulfillment overview

/v1/fulfillment/* covers international logistics after goods are in the HIOBuy warehouse. Domestic buying: Procurement orders.

Requires warehouse fulfillment on your app (Portal authorization). Self-fulfillment apps get 403 FULFILLMENT_MODE_NOT_SUPPORTED.

API availability {#availability}

PathStatus
/v1/fulfillment/shipments/*Planned — spec stable; Gateway rollout in progress
/v1/fulfillment/balancePlanned
/v1/shipments (legacy)Deprecated

End-to-end flow {#end-to-end-flow}

  1. Create procurement order → seller ships to warehouse
  2. Order detail → parcel_nos[] when inbound
  3. Freight estimate → pick shipping_channel_code
  4. Shipment preview → exact price
  5. Create shipment → shipment_id
  6. Pay shipment → deduct wallet
  7. International tracking

Endpoint guide

TopicPathDoc
Quick freight quotePOST .../freight/estimateFreight estimate
Exact warehouse quotePOST .../previewShipment preview
Create / pay / cancel / detailPOST .../shipments/*Shipments
International tracePOST .../logistics/traceTracking
Wallet balanceGET /v1/fulfillment/balanceBalance
Response fields—Fulfillment response models
Item attributesGET .../item-attributesFreight estimate

Warehouse-mode procurement

/v1/orders/* paths unchanged; Gateway forwards to HIOBuy. Product APIs still call marketplaces directly.

Domestic trace: order logistics trace (proxied in warehouse mode).

Errors

FULFILLMENT_MODE_NOT_SUPPORTED, PARCEL_NOT_FOUND, INVALID_SHIPPING_CHANNEL, INSUFFICIENT_BALANCE — see Errors.