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.

Optional idempotency header

Send Idempotency-Key when creating an inbound notice. It is optional but recommended for retries and concurrent submissions. Use one unique key per logical inbound notice and reuse it only for the same request.

POST /v1/fulfillment/inbounds/create
Authorization: Bearer <API_KEY>
Content-Type: application/json
Idempotency-Key: 803627de-c701-4ddf-94b7-b0c2fdad4f02

The Gateway forwards this header to the warehouse. The legacy X-Idempotency-Key header is accepted for compatibility, but new integrations should use Idempotency-Key.

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
    }
  ]
}

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.

Duplicate and concurrent requests

A duplicate tracking number, duplicate external_order_id, or idempotency conflict returns HTTP 409. When known, error.details.existing_resource contains a safe package summary so you can recover the existing package_id and tracking number instead of creating another notice.

{
  "error": {
    "code": "EXTERNAL_ORDER_ID_ALREADY_EXISTS",
    "message": "External order id already exists",
    "request_id": "req_...",
    "category": "VALIDATION_ERROR",
    "details": {
      "field": "external_order_id",
      "existing_resource": {
        "type": "package",
        "package_id": "427",
        "tracking_number": "YT1234567890",
        "external_order_id": "MY-ORD-001",
        "status": "PENDING"
      }
    }
  }
}

Relevant codes: EXTERNAL_ORDER_ID_ALREADY_EXISTS, INBOUND_TRACKING_ALREADY_EXISTS, INBOUND_TRACKING_ALREADY_SHIPPED, IDEMPOTENCY_CONFLICT, and IDEMPOTENCY_REQUEST_IN_PROGRESS. For an in-progress request, wait at least error.details.retry_after_ms before retrying with the same key.

Cancel inbound {#cancel}

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

{id} may be the HioBuy package ID or a developer-provided external package/order identifier supported by the warehouse. The Gateway forwards it unchanged as the warehouse packageNum. Numeric-only values are reserved for HioBuy internal IDs, so prefix developer identifiers (for example, pkg_MY-ORD-001) to avoid ambiguity.

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.

Scope: shipment:create.

Package status (reference)

Warehouse package lifecycle codes (canonical):

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

Sandbox fixtures

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

Related

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