Inbound notice (create)

POST /v1/fulfillment/inbounds/create — submit an inbound notice so the warehouse can expect a domestic shipment (tracking number + items + optional value-added services).

Requires warehouse fulfillment (Portal authorization). Self-fulfillment → 403 FULFILLMENT_MODE_NOT_SUPPORTED.

Availability: Sandbox is MOCK. Warehouse-mode live keys forward to the warehouse inbound API.

Scope: shipment:create.

Request body

{
  "tracking_number": "YT1234567890",
  "carrier": "YTO",
  "package_count": 1,
  "total_value": 128.5,
  "currency": "CNY",
  "external_order_id": "MY-ORD-001",
  "supplier_order_id": "1688-xxx",
  "remark": "fragile",
  "sender": {
    "name": "Zhang San",
    "phone": "13800000000",
    "country_code": "CN",
    "province": "Zhejiang",
    "city": "Hangzhou",
    "district": "Yuhang",
    "postcode": "310000",
    "address": "…"
  },
  "items": [
    {
      "name": "Cotton T-Shirt",
      "quantity": "2",
      "unit_price": "64.25",
      "currency": "CNY",
      "hs_code": "610910",
      "image_url": "https://example.com/t.jpg"
    }
  ],
  "services": [
    {
      "service_code": "photo",
      "quantity": 1
    }
  ]
}

Field	Required	Notes
`tracking_number`	Yes	Domestic carrier tracking number
`package_count`	Yes	Number of physical packages
`total_value`	Yes	Declared total value (face value, not fen)
`currency`	No	Default `CNY`. Supported: `CNY`, `USD`, `KRW`
`items[]`	Yes	Line items; `quantity` and `unit_price` are strings
`services[]`	No	`{ service_code, quantity }` — inbound-stage VAS only
`external_order_id`	No	Unique per app
`carrier` / `sender` / `remark` / `supplier_order_id`	No	Optional metadata

Money: Submit face amounts + currency. Unlike shipment routes, this response does not use monetary_unit: CNY_minor and Gateway does not convert to fen.

Success response

HTTP 201:

{
  "success": true,
  "package_id": "pkg_…",
  "tracking_number": "YT1234567890",
  "status": "pending_receive",
  "package_count": 1,
  "external_order_id": null,
  "created_at": "2026-08-16T07:00:00.000Z",
  "request_id": "req_…"
}

Sandbox happy-path IDs use the sbi_ prefix. Success also returns package_id (pkg_*) for package detail.

Cancel inbound {#cancel}

DELETE /v1/fulfillment/inbounds/{id} — cancel a pre-advise while still waiting for warehouse receipt.

Success (HTTP 200):

{
  "success": true,
  "package_id": "pkg_…",
  "status": "cancelled",
  "cancelled_at": "2026-08-16T10:00:00.000Z",
  "request_id": "req_…"
}

Linked package in PENDING becomes DISCARDED in MOCK.

Trigger / case	HTTP	`error.code`
Unknown id / `sb_inb_not_found`	404	`INBOUND_NOT_FOUND`
`sb_inb_received`	409	`INBOUND_ALREADY_RECEIVED`
`sb_inb_shipped` / `sb_inb_consolidated` / already cancelled	409	`INBOUND_NOT_EDITABLE`

Scope: shipment:create.

Package status (reference)

Warehouse package lifecycle codes (canonical):

CODE	EN label	Meaning
`PENDING`	Pending Receipt	Pre-advised; waiting for warehouse receipt
`RECEIVED`	Received	Received into warehouse
`CONSOLIDATED`	Consolidated	Added to consolidation / packing batch
`SHIPPED`	Shipped	Left the HIOBuy warehouse
`DELIVERED`	Delivered	Signed for by overseas recipient
`TRANSFERRING`	Transferring	Moving between fulfillment warehouses
`DISCARDED`	Discarded	Discard workflow completed
`UNCLAIMED`	Unclaimed	At warehouse; cannot match owner / notice
`ARCHIVED`	Archived	Archived after completion

Create MOCK currently returns status: "pending_receive" (aligned with PENDING). Future APIs should use the table above.

Sandbox fixtures

Trigger	Field	HTTP	`error.code`
`sb_inbound_shipped`	`tracking_number`	409	`INBOUND_TRACKING_ALREADY_SHIPPED`
`sb_inbound_exists`	`tracking_number`	409	`INBOUND_TRACKING_ALREADY_EXISTS`
`sb_inbound_bad_tracking`	`tracking_number`	422	`INVALID_TRACKING_NUMBER`
`sb_inbound_external_exists`	`external_order_id`	409	`EXTERNAL_ORDER_ID_ALREADY_EXISTS`
`sb_vas_missing`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_NOT_FOUND`
`sb_vas_unavailable`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_UNAVAILABLE`
`sb_vas_outbound`	`services[].service_code`	422	`VALUE_ADDED_SERVICE_INVALID_STAGE`
`quantity: 0`	`services[].quantity`	422	`VALUE_ADDED_SERVICE_QUANTITY_INVALID`

Missing required fields → 422 INBOUND_VALIDATION_FAILED with details.fields[] (REQUIRED / INVALID_VALUE / …). Conflicts use protocol 4xx, not soft 200.

Errors

See Errors — Inbound / VAS group. Gate code: FULFILLMENT_MODE_NOT_SUPPORTED (maps draft FULFILLMENT_NOT_ENABLED).

Package detail (after create — contract locked)
Fulfillment overview
Create shipment (after parcels are received)
Sandbox

Get Support

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

Email support