Inbound notice (create)

Identity: Create returns a single package_id (pkg_*). There is no separate inbound_id.

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 / Gateway MOCK is live (hio_test_*). Live warehouse upstream forwarding is not wired yet.

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,
  "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.

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

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