API ReferenceShipmentsCreate a shipment

Create a shipment

POST/api/v1/shipments idempotent

Re-quotes the selected service tier server-side, deducts the wallet in live mode (test mode skips), dispatches to the carrier, and returns the full shipment record with pricing snapshot + dispatch result. Requires Idempotency-Key. service_tier_id takes a Service Code (e.g. HKASTDGGSTCM) — list yours via GET /v1/service_tiers. Optional selected_surcharges opts into SIGNATURE / INSURANCE where eligible (check opt_in_availability on POST /v1/rates; on the US priority line signature and insurance are mutually exclusive). Optional ioss_number (IM + 10 digits) overrides the account-level IOSS default for this shipment; EU destinations only.

Parameters

goods_category

stringbody

ioss_number

stringbody

EU IOSS number (IM + 10 digits). Overrides the account-level default for this shipment; EU destinations only. With IOSS, EU VAT prepay is not charged and the number is forwarded to the carrier. The number must belong to your account — your own saved IOSS or a marketplace platform IOSS registered to you (contact support to add one); anything else returns 400 IOSS_NOT_OWNED.

items

array<object>body

metadata

objectbody

parcels*

array<object>body

payment_type

enum (prepaid | cod)body

recipient*

objectbody

reference_no

stringbody

selected_surcharges

array<string>body

Opt-in surcharge codes, e.g. ["SIGNATURE","INSURANCE"]. Eligibility is per service code + destination — check opt_in_availability on POST /v1/rates first. Signature is carrier-gated (cosmetics line; US priority via a carrier-product switch); on the US priority line signature and insurance are mutually exclusive.

sender

objectbody

service_tier_id*

stringbody

Service Code to book (e.g. HKASTDGGSTCM) — list the codes your account can use via GET /v1/service_tiers. The wire name service_tier_id is historical and kept for backwards compatibility.

Responses

Success body

{
  "status": 201,
  "message": "OK",
  "data": {
    "created_at": "2026-05-28T07:44:23.908Z",
    "dispatch": null,
    "id": "IM-2026-0528-9ZNCP3-1",
    "livemode": false,
    "parcels": [
      {
        "weight_kg": 0.5,
        "height_cm": 6,
        "length_cm": 22,
        "width_cm": 18
      }
    ],
    "pricing_snapshot": {
      "currency": "HKD",
      "freight_hkd": 58.5,
      "rate_table_code": "RT-HKASTDGGSTCM-US-v1",
      "rate_table_version": 1,
      "reg_fee_hkd": 36,
      "surcharges": [
        {
          "amount_hkd": 0,
          "code": "<code>"
        }
      ],
      "total_hkd": 94.5
    },
    "recipient": {
      "address": "1 Hacker Way",
      "city": "San Francisco",
      "contact_name": "John Doe",
      "country_code": "US",
      "phone": "+14155551234",
      "district": "CA",
      "postal_code": "94025"
    },
    "reference_no": "PO-2026-0528-0017",
    "sender": null,
    "service_tier_id": "HKASTDGGSTCM",
    "status": "label_created",
    "tracking_number": "IM-2026-0528-9ZNCP3-1"
  }
}

Returned object

Field	Type	Sample
status	number	201
message	string	OK
data	object	{12 keys}