Create Order (International)

Create a new order for shipment to destinations outside Hong Kong.

Endpoint

POST /v1/order/create

Request

Header Parameters

Parameter	Type	Required	Example	Description
`Authorization`	string	Yes	`Bearer YOUR_ACCESS_TOKEN`	Bearer access token used for authentication.
`Content-Type`	string	Yes	`application/json`	Request body content type.

Request Body Schema

application/json

ship_typerequired

string

Shipment type for international orders.

Must be intl.

Example: intl

shipping_providerrequired

string

International shipping provider code.

Reference: Get Rates for valid codes.

Example: fedex_ip_export

senderrequired

json-string

Sender information.

namerequired

string

Sender full name.

Maximum 35 characters.

Example: John Chan

company_name

string

Sender company name.

Maximum 35 characters.

Example: ABC Trading Ltd

mobilerequired

string

Mobile number without country prefix.

Example: 91234567

mobile_prefixrequired

string

Mobile country calling code.

Maximum 5 characters (e.g. +852).

Example: +852

emailrequired

string

Sender email address.

Maximum 50 characters, valid email format.

Example: john@example.com

addressrequired

string

Street address line 1.

5–29 characters.

Example: Unit 12, 3/F, ABC Building

address_line_2

string

Street address line 2.

Maximum 29 characters.

Example: Kwun Tong

address_line_3

string

Street address line 3.

Maximum 29 characters.

Example: Near MTR Station

city

string

City name.

Reference: Get States & Cities for valid values.

Example: Hong Kong

state

string

State or province code.

Reference: Get States & Cities for valid values.

Example: KLN

post_code

string

Postal or ZIP code.

Example: 999077

countryrequired

string

Country code.

Reference: Get Country for full list.

Example: DE

recipientrequired

json-string

Recipient information.

namerequired

string

Recipient full name.

Maximum 35 characters.

Example: David Lee

company_name

string

Recipient company name.

Maximum 35 characters.

Example: XYZ Imports GmbH

mobilerequired

string

Mobile number without country prefix.

Example: 98765432

mobile_prefixrequired

string

Mobile country calling code.

Maximum 5 characters (e.g. +49).

Example: +49

emailrequired

string

Recipient email address.

Maximum 50 characters, valid email format.

Example: david@example.de

addressrequired

string

Street address line 1.

5–29 characters.

Example: 123 Hauptstrasse

address_line_2

string

Street address line 2.

Maximum 29 characters.

Example: 2nd Floor

address_line_3

string

Street address line 3.

Maximum 29 characters.

Example: —

city

string

City name.

Reference: Get States & Cities for valid values.

Example: Berlin

state

string

State or province code.

Reference: Get States & Cities for valid values.

Example: BE

post_code

string

Postal or ZIP code.

Example: 10115

countryrequired

string

Country code.

Reference: Get Country for full list.

Example: DE

tax_code

string

Recipient tax ID or VAT ID.

Example: DE123456789

eori_number

string

EORI number.

Maximum 20 characters.

Example: DE123456789000

shipment_detailrequired

json-string

Shipment and parcel details.

package_typerequired

string

Package type identifier.

Enum: "parcel" "document" "pallet"

Example: parcel

consignment_declaration

string

General description of shipment contents.

Maximum 35 characters.

Example: Electronic accessories

consignment_invoice_number

string

Commercial invoice number or reference.

Maximum 50 characters.

Example: INV-20260227-001

currency

string

Currency for declared values.

Example: USD

Expand for valid values.

Supported values:

Code	Description
`HKD`	Hong Kong Dollar
`USD`	US Dollar
`EUR`	Euro
`CNY`	Chinese Yuan
`GBP`	British Pound
`AED`	UAE Dirham
`ARS`	Argentine Peso
`AUD`	Australian Dollar
`BRL`	Brazilian Real
`CAD`	Canadian Dollar
`CHF`	Swiss Franc
`CZK`	Czech Koruna
`DKK`	Danish Krone
`EGP`	Egyptian Pound
`HUF`	Hungarian Forint
`IDR`	Indonesian Rupiah
`ILS`	Israeli Shekel
`INR`	Indian Rupee
`JPY`	Japanese Yen
`KES`	Kenyan Shilling
`KRW`	South Korean Won
`MOP`	Macanese Pataca
`MXN`	Mexican Peso
`MYR`	Malaysian Ringgit
`NOK`	Norwegian Krone
`NZD`	New Zealand Dollar
`PHP`	Philippine Peso
`PLN`	Polish Zloty
`RUB`	Russian Ruble
`SAR`	Saudi Riyal
`SEK`	Swedish Krona
`SGD`	Singapore Dollar
`THB`	Thai Baht
`TRY`	Turkish Lira
`TWD`	New Taiwan Dollar
`ZAR`	South African Rand

reason_of_export

string

Reason for export. Must be one of the supported consignment types.

Example: Sale of goods

Expand for valid values.

Supported values:

Value
`Gift`
`Return of goods`
`Sale of goods`
`Commercial sample`
`Documents`
`Personal, Not for resale`
`Personal effects (transfer of residence)`
`Return of repair`
`Return after repair`
`Airsoft toys`

parcel_listrequired

array

Array of parcel details. At least one parcel is required.

Example: Reference parcel object below

act_weightrequired

string

Actual parcel weight in kg.

Decimal string, minimum 0.01 kg.

Example: "1.25"

heightrequired

string

Parcel height in cm.

Decimal string, minimum 0 cm.

Example: "10"

widthrequired

string

Parcel width in cm.

Decimal string, minimum 0 cm.

Example: "15"

lengthrequired

string

Parcel length in cm.

Decimal string, minimum 0 cm.

Example: "20"

insurance_fee

string

Insurance fee amount.

Numeric string.

Example: "100.00"

item_remarks

string

Parcel-level remarks.

Maximum 30 characters.

Example: Handle with care

declaration_listrequired

array

Array of declaration items (description, qty, single_price, etc.). At least one required.

Example: Reference declaration object below

descriptionrequired

string

Item description for customs.

1–35 characters.

Example: Bluetooth headset

qtyrequired

string

Quantity of items.

Integer string, minimum 1.

Example: "2"

single_pricerequired

string

Declared price per unit.

Decimal string, minimum 0.

Example: "50.00"

single_weight

string

Weight per unit in kg.

Decimal string.

Example: "0.20"

hscode

string

Harmonized System (HS) code.

Maximum 10 characters.

Example: 851762

origin

string

Country of origin. Must follow ISO 3166-1 alpha-2 (e.g. US, HK, GB) or full country names.

Example: CN

item_length

string

Item length in cm.

Decimal string.

Example: 50

item_width

string

Item width in cm.

Decimal string.

Example: 30

item_height

string

Item height in cm.

Decimal string.

Example: 15

unit

string

Unit of measurement. Default: PCS if not provided.

Example: PCS

Expand for valid values.

Supported values:

Code	Description
`PCS`	Pieces
`BOX`	Boxes
`BG`	Bags
`PRS`	Pairs
`CT`	Cartons
`SET`	Set
`DOZ`	Dozen
`OTH`	No Unit Required

battery

json-string

Battery information.

If present, type and location required.

Example: {"type":"chargeable","location":"inside"}

battery.type

string

Battery type when battery is provided.

Enum: "chargeable" "nonchargeable"

Example: chargeable

battery.location

string

Battery placement when battery is provided.

Enum: "inside" "outside"

Example: inside

shipment_options

json-string

Optional shipment settings.

Note: Omit if not needed. Empty string "" is accepted and defaults apply. All properties in this object are optional.

tax_party

string

Party responsible for duties and taxes.

Enum: "sender" "recipient"

Example: sender

ioss_number

string

IOSS number for EU shipments.

Maximum 50 characters.

Example: IM2760000742

fedex_account_number

string

FedEx account number.

Exactly 9 digits only when using FedEx IC Export to Puerto Rico with tax_party = recipient. Otherwise accepted without format check.

Example: 123456789

recipient_signature

string

Signature requirement option.

Example: O

Expand for valid values.

Signature options:

Value	Description
`N`	No signature required (default)
`O`	Signature confirmation required
`A`	Adult signature required

client_remarks

string

Optional internal client notes.

Maximum 500 characters.

Example: Urgent shipment

confirm_shipment

string

Indicates whether the shipment should be confirmed and created immediately.

Enum: "Y" "N"

Example: Y

Example Request Body

{
  "ship_type": "intl",
  "shipping_provider": "fedex_ip_export",
  "sender": {
    "name": "John Doe",
    "company_name": "ABC Company Limited",
    "mobile": "91234567",
    "mobile_prefix": "+852",
    "email": "johndoe@test.com",
    "address": "Unit 1203, 2 Harbour Road",
    "address_line_2": "Convention Plaza",
    "address_line_3": "Tower 1",
    "city": "CENTRAL",
    "state": "CENTRAL AND WESTERN",
    "post_code": "00000",
    "country": "HK"
  },
  "recipient": {
    "name": "Hans Mueller",
    "company_name": "Mueller Company Limited",
    "mobile": "1512345678",
    "mobile_prefix": "+49",
    "email": "muller@test.com",
    "address": "Musterstrasse 123",
    "address_line_2": "Building A",
    "address_line_3": "3rd Floor",
    "city": "Berlin",
    "state": "BE",
    "post_code": "10115",
    "country": "DE",
    "tax_code": "DE123456789",
    "eori_number": "DE123456789012345"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "consignment_declaration": "Commercial goods for resale",
    "consignment_invoice_number": "INV-2024-0001",
    "currency": "EUR",
    "reason_of_export": "Gift",
    "parcel_list": [
      {
        "act_weight": "0.50",
        "height": "10",
        "width": "15",
        "length": "20",
        "insurance_fee": "0",
        "item_remarks": "Electronics accessories",
        "declaration_list": [
          {
            "description": "Wireless earbuds with charging case",
            "qty": "2",
            "unit": "PCS",
            "single_price": "50.00",
            "single_weight": "0.50",
            "hscode": "85183000",
            "origin": "HK",
            "item_length": "50",
            "item_width": "30",
            "item_height": "15",
            "battery": {
              "type": "chargeable",
              "location": "inside"
            }
          }
        ]
      }
    ]
  },
  "shipment_options": {
    "tax_party": "sender",
    "ioss_number": "IM1234567890",
    "fedex_account_number": "123456789",
    "recipient_signature": "O"
  },
  "client_remarks": "Shipping from HK to DE",
  "confirm_shipment": "Y"
}

Example request

curl -X POST "${API_URL}/v1/order/create" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "ship_type": "intl",
  "shipping_provider": "fedex_ip_export",
  "sender": { "name": "John Doe", "mobile": "91234567", "mobile_prefix": "+852", "email": "johndoe@test.com", "address": "Unit 1203, 2 Harbour Road", "city": "CENTRAL", "state": "CENTRAL AND WESTERN", "post_code": "00000", "country": "HK" },
  "recipient": { "name": "Hans Mueller", "mobile": "1512345678", "mobile_prefix": "+49", "email": "muller@test.com", "address": "Musterstrasse 123", "city": "Berlin", "state": "BE", "post_code": "10115", "country": "DE" },
  "shipment_detail": {
    "package_type": "parcel",
    "consignment_declaration": "Commercial goods for resale",
    "currency": "EUR",
    "reason_of_export": "Gift",
    "parcel_list": [{ "act_weight": "0.50", "height": "10", "width": "15", "length": "20", "declaration_list": [{ "description": "Wireless earbuds", "qty": "2", "unit": "PCS", "single_price": "50.00", "origin": "HK", "item_length": "50", "item_width": "30", "item_height": "15" }] }]
  },
  "client_remarks": "Shipping from HK to DE",
  "confirm_shipment": "Y"
}'

Responses

200 Success

Response schema: application/json

data

json-string

Order creation result.

Expand for fields.

order_id

string

Internal order identifier.

Example: 3565991

ship_type

string

Shipping type for this order.

Example: intl

order_status

string

Order status.

Example: READY_TO_SHIP

quote_price

string

Quoted shipping price in HKD.

Example: 410.00

confirm_shipment

string

Indicates whether order is confirmed (Y) or saved only (N).

Example: Y

tracking_number

string

Tracking number when confirmed.

Example: 888303373836

client_remarks

string

Client notes for the order.

Example: Shipping from HK to DE

create_time

string

Order creation timestamp (ISO 8601).

Example: 2026-01-29T18:41:41+08:00

message

string

Human-readable status message.

Example: confirmed and assigned with a tracking number

Response sample

{
  "data": {
    "order_id": "3565991",
    "ship_type": "intl",
    "order_status": "READY_TO_SHIP",
    "quote_price": "410.00",
    "confirm_shipment": "Y",
    "tracking_number": "888303373836",
    "client_remarks": "Shipping from HK to DE",
    "create_time": "2026-01-29T18:41:41+08:00",
    "message": "confirmed and assigned with a tracking number"
  }
}

400 Bad Request

Response schema: application/json

code

string

Error code returned by the API.

Example: 400000

code_reason

string

Machine-readable error reason.

Example: BAD_REQUEST

message

string

Summary of the error.

Example: Bad Request

error_trace

array

List of validation errors.

field

string

Request field that failed.

Example: shipping_provider

message

string

Human-readable explanation for this error.

Example: shipping_provider is required

Response sample

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      { "field": "shipping_provider", "message": "shipping_provider is required" },
      { "field": "shipment_detail", "message": "shipment_detail is required" }
    ]
  }
}

401 Unauthorized

Response schema: application/json

code

string

Error code (e.g. 401000, 401020).

Example: 401000

code_reason

string

Machine-readable reason.

Example: UNAUTHORIZED

message

string

Human-readable message.

Example: Unauthorized

Response sample

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

403 Forbidden

Response schema: application/json

error

json-string

Access forbidden for this resource.

404 Not Found

Response schema: application/json

error

json-string

Resource or endpoint not found.

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"
  }
}

Endpoint​

Request​

Header Parameters​

Request Body Schema​

Example Request Body​

Example request​

Responses​

200 Success​

200 Success

400 Bad Request​

400 Bad Request

401 Unauthorized​

401 Unauthorized

403 Forbidden​

403 Forbidden

404 Not Found​

404 Not Found

500 Failure​

500 Failure

Endpoint

Request

Header Parameters

Request Body Schema

Example Request Body

Example request

Responses

200 Success

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Failure