API ReferencePickupsList pickups

List pickups

GET/api/v1/pickups

The account's pickups, newest first, including the ones arranged in the web portal. Keyset pagination. One pickup is one pickup request to the carrier warehouse: a booking that spans several destinations produces several pickups. shipment_ids of a pickup are pickup-selection ids; tracking_numbers carries the ids that /v1/shipments accepts. updated_after is an RFC 3339 date-time with a timezone; a pickup counts as updated when the pickup itself or the manifest that carries its fee changed, and updated_at is the later of the two, so a fee settled after your last poll shows up in the next incremental poll. Requires scope pickups:read.

Parameters

limit

integerquery

cursor

stringquery

Opaque cursor from a previous response's next_cursor field. Only valid with the same filters.

status

stringquery

pickup_date

stringquery

A real calendar date, YYYY-MM-DD (Hong Kong).

updated_after

stringquery

RFC 3339 date-time with a timezone (Z or ±hh:mm), e.g. 2026-10-19T00:00:00Z. Anything else is a 400.

Responses

Success body

{
  "status": 200,
  "message": "OK",
  "data": {
    "data": [
      {
        "id": "6710a1b2c3d4e5f607182960",
        "livemode": false,
        "simulated": true,
        "manifest_id": null,
        "address_group_id": "6710a1b2c3d4e5f607182951",
        "status": "requested",
        "destination": "yunexpress",
        "parcel_carriers": [
          "yunexpress"
        ],
        "shipment_ids": [
          "6710a1b2c3d4e5f607182931"
        ],
        "tracking_numbers": [
          "IM2610190000000001"
        ],
        "pickup_date": "2026-10-21",
        "scheduled_pickup_date": "2026-10-21",
        "pickup_window": {
          "start": "13:00",
          "end": "17:00",
          "timezone": "Asia/Hong_Kong"
        },
        "pickup_address": {
          "name": "Chan Tai Man",
          "phone": "+852 91234567",
          "email": "ops@example.com",
          "address_line": "Unit 1203, 12/F, Tower 2, Kowloon Commerce Centre, 51 Kwai Cheong Road, Kwai Chung"
        },
        "carrier_tracking_number": null,
        "pickup_courier": null,
        "failure_reason": null,
        "fee": {
          "scope": "address_group",
          "state": "provisional",
          "estimated_hkd": 45,
          "charged_hkd": 0,
          "refunded_hkd": 0
        },
        "cancellation": {
          "allowed": true,
          "deadline": "2026-10-19T04:12:40.123Z",
          "reason_code": null
        },
        "created_at": "2026-10-19T03:12:40.123Z",
        "updated_at": "2026-10-19T03:12:40.123Z"
      }
    ],
    "next_cursor": null
  }
}

Returned object

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