Packages (list, detail, tracking & unclaimed)

Warehouse packages after inbound notice.

Availability: Sandbox is MOCK. Warehouse-mode live keys forward package list, detail, tracking, unclaimed list, and unclaimed claim to the warehouse.

Requires warehouse fulfillment.

After inbound create, use returned package_id (pkg_*). Carrier / warehouse waybill is tracking_number only.

Lifecycle {#lifecycle}

Main path (solid): inbound notice → received → consolidated → shipped → delivered.
Side paths (dashed): unmatched inbound → UNCLAIMED (claim back to RECEIVED); RECEIVED may go to DISCARDED.

Also: TRANSFERRING (warehouse transfer), ARCHIVED (after completion).

List Unclaimed Packages

Returns packages received by HioBuy Fulfillment that could not be automatically matched to an inbound notice. Tracking numbers are partially masked for security.

Query: carrier, received_from, received_to, page, page_size.
No full tracking-number search. List never returns full tracking, sender, items, photos, or inbound/developer secrets.

IDs in the list are display-only. Claim does not take an unclaimed id — POST the full domestic tracking number.

Sandbox list: ucp_01K2ABCDEF1234567890 → masked SF1234****9012 (claim with SF123456789012).

Claim an Unclaimed Package

Claims an unrecognized warehouse package by verifying its full domestic tracking number. Success creates a normal pkg_* package.

{
  "tracking_number": "SF123456789012"
}

Success returns a package id with full tracking_number, status: RECEIVED, claimed: true.
Unknown tracking → 404 UNCLAIMED_PACKAGE_NOT_FOUND. Claiming the same number again → 409 PACKAGE_ALREADY_CLAIMED.

Full contract: internal unclaimed-packages.md.

Package tracking vs shipment tracking

Branch UI on stable event.code (never on title / description). Event registry includes INBOUND_CREATED, PACKAGE_RECEIVED, PACKAGE_PUTAWAY, PACKAGE_UNCLAIMED / PACKAGE_CLAIMED, transfer start/complete, PACKAGE_EXCEPTION, service codes, PACKAGE_CONSOLIDATED / PACKAGE_SHIPPED / PACKAGE_DELIVERED, discard/archive.

PACKAGE_EXCEPTION may keep lifecycle status: RECEIVED — stage vs problem are separate.

Tracking example (sb_pkg_shipped)

{
  "package_id": "sb_pkg_shipped",
  "status": "SHIPPED",
  "tracking_number": "SF123456789012",
  "carrier": "SF Express",
  "events": [
    {
      "code": "INBOUND_CREATED",
      "status": "PENDING"
    },
    {
      "code": "PACKAGE_RECEIVED",
      "status": "RECEIVED"
    },
    {
      "code": "PACKAGE_PUTAWAY",
      "status": "RECEIVED"
    },
    {
      "code": "SERVICE_COMPLETED",
      "status": "RECEIVED"
    },
    {
      "code": "PACKAGE_CONSOLIDATED",
      "status": "CONSOLIDATED"
    },
    {
      "code": "PACKAGE_SHIPPED",
      "status": "SHIPPED"
    }
  ]
}

Full event fields: id, code, status, title, description, optional related_resource / exception / transfer, occurred_at. No location_code.

List {#list}

List rows are intentionally smaller than detail — no items[], full sender, services[], exception files, fee breakdown, or full timestamps.

Query parameters

Cursor pagination may be added later for large catalogs. Warehouse live keys POST the same filters to packages/index; sandbox uses page offset.

List item example

{
  "id": "pkg_01K2ABCDEF1234567890",
  "status": "RECEIVED",
  "archived": false,
  "external_order_id": "KR-20260816-001",
  "supplier_order_id": "1688-987654321",
  "tracking_number": "SF123456789012",
  "carrier": "SF Express",
  "warehouse": {
    "weight": {
      "value": 2.35,
      "unit": "kg"
    },
    "dimensions": {
      "length": 42,
      "width": 30,
      "height": 18,
      "unit": "cm"
    }
  },
  "attributes": {
    "goods_type": "GENERAL",
    "tags": [
      "GENERAL_GOODS"
    ]
  },
  "condition": {
    "status": "NORMAL",
    "has_exception": false
  },
  "item_summary": {
    "item_count": 2,
    "total_quantity": 20
  },
  "service_summary": {
    "total": 2,
    "pending": 0,
    "processing": 0,
    "completed": 2
  },
  "shipment": {
    "shipment_id": null
  },
  "created_at": "2026-08-16T07:40:00Z",
  "received_at": "2026-08-16T08:05:00Z",
  "updated_at": "2026-08-16T09:30:00Z"
}

List response envelope

{
  "data": [],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 128,
    "total_pages": 7
  },
  "request_id": "req_…"
}

Detail {#detail}

GET /v1/fulfillment/packages/{package_id} — full package after inbound.

Missing package → 404 PACKAGE_NOT_FOUND.

Response layout (12 blocks)

identity · status · order/tracking · items · sender · warehouse
attributes · condition · services · fees · claim/transfer/shipment · timestamps

Money: face value + currency (not fen / CNY_minor).
Items: quantity and unit_price are numbers.
Identity: id (programmatic) + tracking_number (waybill).

Locked decisions

1. items.quantity / unit_price → numbers
2. attributes.goods_type (GENERAL | SENSITIVE) + tags[]
3. Lifecycle status vs condition
4. Paid photos → services[].result.files; optional warehouse_files
5. fees summary only
6. warehouse is measurements only — no location_code. Use GET /v1/fulfillment/locations for warehouse sites.

Exception codes (v1)

DAMAGED · MISSING_ITEM · QUANTITY_MISMATCH · WRONG_ITEM · WRONG_SKU · PACKAGING_DAMAGED · UNKNOWN_ITEM · OTHER

Package status

PENDING, RECEIVED, CONSOLIDATED, SHIPPED, DELIVERED, TRANSFERRING, DISCARDED, UNCLAIMED, ARCHIVED.

Detail example

See internal packages.md for the full detail JSON (includes tracking_number, services, fees, timestamps).

Related

• Inbound notice
• Fulfillment overview
• Errors