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.

For inbound create, shipment create, and shipment pay, the optional Idempotency-Key header protects retries and concurrent calls. Use a new key for each logical operation and reuse it only for the identical request. Duplicate conflicts may include the existing package, shipment, or payment in error.details.existing_resource.

Monetary unit {#monetary-unit}

Standard JSON responses on money-bearing fulfillment routes include top-level monetary_unit: "CNY_minor". All { amount, currency } fields are CNY fen (1 yuan = 100 fen). See Fulfillment response models.

API availability {#availability}

PathStatus
/v1/fulfillment/inbounds/createLive warehouse simple-store when warehouse mode; mock in sandbox
/v1/fulfillment/packagesLive warehouse packages/index when warehouse mode; mock in sandbox
/v1/fulfillment/packages/{package_id}Live warehouse packages/detail/{id} when warehouse mode; mock in sandbox
/v1/fulfillment/packages/{package_id}/trackingLive warehouse packages/logs/{id} when warehouse mode; mock in sandbox
/v1/fulfillment/unclaimed-packagesLive warehouse list + claim when warehouse mode; mock in sandbox
/v1/fulfillment/returnsMock — return-to-seller create/list/confirm/cancel
/v1/fulfillment/locationsLive warehouse warehouse when warehouse mode; mock in sandbox
/v1/fulfillment/value-added-servicesLive warehouse services when warehouse mode; mock in sandbox
/v1/fulfillment/service-requestsMock — create/list/detail/confirm
/v1/fulfillment/shipments/{id}/interceptLive warehouse shipments/set-exceptional when warehouse mode; mock in sandbox
/v1/fulfillment/shipmentsLive warehouse shipments/index when warehouse mode; mock in sandbox
/v1/fulfillment/shipping/channelsLive warehouse channel catalog when warehouse mode; mock in sandbox
/v1/fulfillment/shipping/quotesLive warehouse quotes when warehouse mode; mock in sandbox
/v1/fulfillment/shipments/*Available (mock / warehouse HTTP when configured)
/v1/fulfillment/balanceAvailable
/v1/shipments (legacy)Deprecated

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

  1. Create procurement order → seller ships to warehouse
    or Inbound notice for parcels you already control
  2. Package detail / tracking → warehouse measurements / exceptions / VAS / fulfillment timeline
    or Order detail → tracking_numbers[] when inbound from procurement
  3. Shipping channels for capabilities, then Shipping quotes → pick quotes[].channel.code
  4. Create shipment → id / order_sn (PENDING)
  5. Warehouse packing & final measurement → boxes[], final weight / dimensions, final freight
  6. Shipment ready for payment (WAIT_PAYMENT) → see detail; paying earlier returns 409 SHIPMENT_NOT_READY_FOR_PAYMENT
  7. Pay shipment → deduct wallet
  8. List / detail → lightweight rows, or boxes / packing files / timeline / first/last-mile numbers
    Optional: Intercept if you need to hold a WAIT_SHIP / SHIPPED shipment
  9. International tracking → scan events

New to warehouse fulfillment? Follow the WH-DEV testing guide to test the complete workflow, including warehouse packing and settlement.

Start WH-DEV testing →

Endpoint guide

TopicPathDoc
Inbound noticePOST .../inbounds/createInbounds
Package detail / tracking / unclaimedGET .../packages/* · unclaimed-packagesPackages
ReturnsPOST/GET .../returns · confirm/cancelReturns
LocationsGET .../locationsLocations
Value-added servicesGET .../value-added-servicesVAS
Service requestsPOST/GET .../service-requests · confirmService requests
Shipping channelsGET .../shipping/channelsShipping channels
Shipping quotesPOST .../shipping/quotesShipping quotes
Create / pay / cancel / interceptPOST .../shipments/create · {id}/pay · {id}/cancel · {id}/interceptShipments
Shipment listGET .../shipmentsShipments · list
Shipment detailGET .../shipments/{id}Shipments · detail
International trackingGET .../shipments/{id}/trackingTracking
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).

Lifecycle diagrams {#lifecycle}

State diagrams: Packages, Shipments, Returns.

Errors

FULFILLMENT_MODE_NOT_SUPPORTED, SHIPMENT_CREATE_EXCEPTION, SHIPMENT_CREATE_FAILED, PARCEL_NOT_FOUND, EXTERNAL_ORDER_ID_ALREADY_EXISTS, SHIPMENT_NOT_READY_FOR_PAYMENT, SHIPMENT_ALREADY_PAID, INSUFFICIENT_BALANCE, NOT_FOUND (SHIPMENT_NOT_EXISTS), intercept codes (SHIPMENT_NOT_FOUND, SHIPMENT_NOT_INTERCEPTABLE, SHIPMENT_INTERCEPTION_ALREADY_REQUESTED) — see Errors and Shipments.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support