国際フルフィルメント概要

/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.

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/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. Freight estimate → pick shipping_channel_code
  4. Create shipment → id / order_sn (exact price on create)
  5. Pay shipment → deduct wallet
  6. 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
  7. International tracking → scan events

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
Quick freight quotePOST .../shipping/quotesFreight estimate
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).

Errors

FULFILLMENT_MODE_NOT_SUPPORTED, SHIPMENT_CREATE_EXCEPTION, PARCEL_NOT_FOUND, EXTERNAL_ORDER_ID_ALREADY_EXISTS, 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