API ReferencePickupsPreview a pickup

Preview a pickup

POST/api/v1/pickups/preview

Validate and price a pickup without arranging it. No pickup data is saved: no address, no account switch, no booking, no claim on the shipments (the request itself is still recorded in the API access log, like every API call). Returns a preview_token (5 minutes) and a booking_intent_id for POST /v1/pickups. will_enable_multi_pickup: true warns that arranging this pickup will switch the account to multiple pickup addresses (irreversible); the preview itself never does. A new preview replaces nothing and reserves nothing: it only gives a new token. Every preview is a fresh quote and needs no Idempotency-Key. pickup_slot is validated here and again at booking (it is not bound to the token). Requires scope pickups:write.

Parameters

address

objectbody

A Hong Kong address to use directly. An address equal to one already on file is reused; otherwise it is saved.

address_id

stringbody

An existing pickup address. Send together with address_resolved_version; mutually exclusive with address.

address_resolved_version

stringbody

mode*

enum (fastest | specific_date)body

parcel_declarations

objectbody

Per destination box count and weight per box.

pickup_date

stringbody

A real calendar date, YYYY-MM-DD (Hong Kong). Required for specific_date, forbidden for fastest.

pickup_slot

enum (morning | afternoon | evening)body

shipment_ids*

array<string>body

shipment_id values from GET /v1/pickups/eligible-shipments.

simulation

objectbody

Test keys only: steers the sandbox simulator. outcome success (default) walks the pickup through submitted, driver_dispatched, picked_up and arrived_at_warehouse within about four minutes; failure makes the submission fail, so the pickup ends as failed. A failed test pickup keeps holding its shipments until it is cancelled, so cancel it within one hour of arranging it: after that it can no longer be cancelled and its test shipment stays held (create a new test shipment instead). Rejected with 400 for live keys.

Responses

Success body

{
  "status": 200,
  "message": "OK",
  "data": {
    "preview_token": "<preview_token from POST /v1/pickups/preview>",
    "expires_at": "2026-10-19T03:17:40.123Z",
    "booking_intent_id": "3b9f0c1e-7a52-4d86-9c3e-0f4a1d2b6e75",
    "livemode": false,
    "pickup_date": "2026-10-21",
    "destination_mode": "per_carrier",
    "route_dates": {
      "yunexpress": "2026-10-21"
    },
    "address": {
      "address_id": "6710a1b2c3d4e5f607182940",
      "alias": "API 7f3a91c2",
      "will_be_created": true,
      "resolved_version": "9d1f4c6a2b8e3057a1c94d2e6f70b3185a2c9e4d7f6018b3c5a2e9d4f1b70c63",
      "address": {
        "country": "HK",
        "name": "Chan Tai Man",
        "company": "Example Trading Ltd",
        "email": "ops@example.com",
        "phone": "+85291234567",
        "address_line1": "Unit 1203, 12/F, Tower 2, Kowloon Commerce Centre, 51 Kwai Cheong Road",
        "city": "Hong Kong",
        "district": "Kwai Chung"
      }
    },
    "will_enable_multi_pickup": false,
    "shipments": [
      {
        "shipment_id": "6710a1b2c3d4e5f607182931",
        "tracking_number": "IM2610190000000001",
        "reference_no": "PO-2026-1019-0003",
        "carrier": "yunexpress",
        "destination": "yunexpress",
        "recipient_country": "US",
        "created_at": "2026-10-19T02:58:11.402Z",
        "livemode": false
      }
    ],
    "fee": {
      "state": "provisional",
      "free": false,
      "group_estimated_hkd": 45,
      "free_threshold_parcels": 5,
      "manifest_total_parcel_count": 1,
      "manifest_total_estimated_hkd": 45,
      "quota_conflicts": []
    }
  }
}

Returned object

Field	Type	Sample
status	number	200
message	string	OK
data	object	{11 keys}