Skip to main content

Submit Pickup (International)

Schedule a pickup for an international order.

Endpoint​

POST /v1/pickup/submit

Request​

Header Parameters​

ParameterTypeRequiredExampleDescription
AuthorizationstringYesBearer YOUR_ACCESS_TOKENBearer token used for authentication.
Content-TypestringYesapplication/jsonRequest body content type.

Request Body Schema​

application/json
order_idrequired
string
Numeric order identifier.
Digits only (0–9).
Example: 3570983
pickup_daterequired
string
Pickup date in HKT (UTC+08:00).
Format: YYYY-MM-DD.
Example: 2026-02-25
pickup_time_startrequired
string
Start time of pickup window.
Format: HH:MM.
Example: 09:30
pickup_time_endrequired
string
End time of pickup window.
Format: HH:MM.
Note: Must be after pickup_time_start and fall within the carrier's available time range.
Example: 12:00
pickup_locationrequired
string
Location within the building where the parcel will be collected.
Example: Reception
Expand for supported values.
Supported values for pickup_location:
Value
Back Door
Downstairs
Front Door
Garage
Guard Room
Mail Room
Office
Receiving
Reception
Shipping
Side Door
Third Party
Upstairs
Warehouse
pickup_addressrequired
json-string
Pickup address and contact details.
Note: Required and optional fields must follow the format and length rules described below.
namerequired
string
Contact name.
English characters only.
mobilerequired
string
Local phone number.
Digits only, maximum 11 characters.
addressrequired
string
First line of pickup address.
Maximum 29 characters.
cityrequired
string
City name.
Reference: Get States & Cities for valid values.
staterequired
string
State or province.
Reference: Get States & Cities for valid values. Must match a supported subdivision for the specified country.
countryrequired
string
Full country name.
Reference: Get Country for full list.
company_name
string
Full company name.
Maximum 35 characters.
address_line_2
string
Second line of pickup address.
Maximum 29 characters.
address_line_3
string
Third line of pickup address.
Maximum 29 characters.
post_code
string
Postal or ZIP code.
email
string
Contact email address.
Must be a valid email format.

Example request body​

{
  "order_id": "8411856",
  "pickup_date": "2026-03-08",
  "pickup_time_start": "09:30",
  "pickup_time_end": "18:30",
  "pickup_location": "Reception",
  "pickup_address": {
    "name": "John Doe",
    "company_name": "ABC Company Limited",
    "mobile": "0412345678",
    "address": "Unit 1203, 2 Harbour Road",
    "address_line_2": "Room2",
    "address_line_3": "Street3",
    "city": "HUNG HOM",
    "state": "KOWLOON CITY",
    "post_code": "999077",
    "country": "HONG KONG"
  }
}

Example request​

curl -X POST "${API_URL}/v1/pickup/submit" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "order_id": "8411856",
  "pickup_date": "2026-03-08",
  "pickup_time_start": "09:30",
  "pickup_time_end": "18:30",
  "pickup_location": "Reception",
  "pickup_address": {
    "name": "John Doe",
    "company_name": "ABC Company Limited",
    "mobile": "0412345678",
    "address": "Unit 1203, 2 Harbour Road",
    "address_line_2": "Room2",
    "address_line_3": "Street3",
    "city": "HUNG HOM",
    "state": "KOWLOON CITY",
    "post_code": "999077",
    "country": "HONG KONG"
  }
}'

Responses​

200 Success​

200 Success

Response schema: application/json
data
object
Pickup submission result.
Expand for fields.
order_id
string
Order ID.
Example: 3570983
ship_type
string
Shipment type. Always intl for this endpoint.
tracking_number
string
Carrier tracking number (waybill).
Note: May be null when pickup is deferred.
pickup_ref
string
Pickup reference assigned by the carrier.
Note: May be null when pickup is deferred.
pickup_date
string
Confirmed pickup date.
Example: 2026-02-25
order_status
string
Updated order status.
pickup_req_id
string
System-generated pickup request ID.
Example: 22423
is_pending_pickup
string
Indicates whether the order is still pending pickup submission to the carrier.
Example: false
message
string
Informational message. Always OK on success.
Example: OK

Response sample (Normal Pickup)

{
  "data": {
    "order_id": "8411856",
    "ship_type": "intl",
    "tracking_number": "889012345678",
    "pickup_ref": "29BAB886970",
    "pickup_date": "2026-02-25",
    "order_status": "PENDING_PICKUP",
    "pickup_req_id": "22423",
    "is_pending_pickup": "false",
    "message": "OK"
  }
}

Response sample (Deferred Pickup)

Note: For deferred pickups (scheduled for a future date), the pickup request will only be sent to the carrier on the selected pickup date.

{
  "data": {
    "order_id": "8411856",
    "ship_type": "intl",
    "tracking_number": "889128368441",
    "pickup_ref": null,
    "pickup_date": "2026-03-05",
    "order_status": "PENDING_PICKUP",
    "is_pending_pickup": "true",
    "pickup_req_id": "22558",
    "message": "OK"
  }
}

400 Bad Request​

400 Bad Request

Response schema: application/json
code
string
Error code returned by the API.
Example: 400000
code_reason
string
Error reason.
Example: BAD_REQUEST
message
string
Human-readable message.
Example: Bad Request
error_trace
array
List of validation errors (field and message per item).
field
string
Request field that failed.
message
string
Human-readable message.

Response sample

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      { "field": "order_id", "message": "order_id is required and must be numeric." },
      { "field": "pickup_address", "message": "pickup_address object is required." }
    ]
  }
}

401 Unauthorized​

401 Unauthorized

Response schema: application/json
code
string
Error code.
Example: 401000
code_reason
string
Error reason.
Example: UNAUTHORIZED
message
string
Human-readable message.
Example: Unauthorized

Response sample

{
  "error": {
    "code": "401000",
    "code_reason": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

403 Forbidden​

403 Forbidden

Response schema: application/json
error
json-string
Access forbidden for this resource.

404 Not Found​

404 Not Found

Response schema: application/json
error
json-string
Resource or endpoint not found.

500 Failure​

500 Failure

Response schema: application/json
code
string
Error code returned by the API.
Example: 500999
code_reason
string
Machine-readable error reason.
Example: API_ERROR
message
string
Human-readable message.
Example: Api Error, please contact customer service

Response sample

{
  "error": {
    "code": "500999",
    "code_reason": "API_ERROR",
    "message": "Api Error, please contact customer service"
  }
}