Create Order (Local)

Create a new order for shipment within 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 local orders.

Must be local.

Example: local

shipping_providerrequired

string

Local shipping provider code.

Reference: Get Rates for valid codes.

Example: sf_expresshk_local

senderrequired

json-string

Sender information.

namerequired

string

Sender full name.

Example: John Doe

mobilerequired

string

Mobile number without country prefix.

Example: 64105317

mobile_prefixrequired

string

Mobile country calling code.

Example: 852

string

Sender email address.

Maximum 50 characters, valid email format.

Example: cs@example.com

addressrequired

string

Full Address.

Minimum 5 characters.

Example: Rm2211, 9 Chong Yip Street, Ngau Tau Kok, Hong Kong

recipientrequired

json-string

Recipient information.

namerequired

string

Recipient full name.

Example: 小編姐姐

mobilerequired

string

Mobile number without country prefix.

Example: 64105317

mobile_prefixrequired

string

Mobile country calling code.

Example: 852

string

Recipient email address.

Example: cs@fuuffy.com

addressrequired

string

Full Address.

Minimum 5 characters.

Example: 香港九龍牛頭角創業街9號2211室

shipment_detailrequired

json-string

Shipment and parcel details.

package_typerequired

string

Package type identifier.

Enum: "parcel" "document" "envelope"

Example: parcel

consignment_declarationrequired

string

General description of shipment contents.

Maximum 35 characters.

Example: 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: "0.5"

length

string

Parcel length in cm.

Decimal string, minimum 0 cm.

Example: "23"

width

string

Parcel width in cm.

Decimal string, minimum 0 cm.

Example: "14"

height

string

Parcel height in cm.

Decimal string, minimum 0 cm.

Example: "10"

insurance_fee

string

Insurance fee amount.

Numeric string. Default "0".

Example: "0"

parcel_itemsrequired

array

Array of items in this parcel.

Example: Reference parcel item object below.

namerequired

string

Item name.

Example: Toy

qtyrequired

string

Quantity of items.

Example: "1"

single_valuerequired

string

Single item value in HKD.

Example: "200.00"

sku

string

Stock keeping unit identifier for this item.

Example: SKU-001

bar_code_eid

string

Barcode or external item ID.

Example: 1234567890

is_pre_order

string

Whether this item is a pre-order.

Enum: "Y" "N"

Example: Y

client_remarks

string

Optional internal client notes.

Maximum 500 characters.

Example: Urgent shipment

is_local_insurance

string

Whether local insurance is requested.

Enum: "Y" "N". Default: "N".

cod

string

Whether cash on delivery is requested.

Enum: "Y" "N". Default: "N".

cod_amount

string

Cash on delivery amount.

Note: Required when cod is Y.

delivery_proof

string

Delivery proof requirement.

Expand for values that can be used.

Supported values:

Value	Description
`E`	Electronic proof of delivery.
`W`	Paper proof of delivery.
`N`	No proof (default).

confirm_shipment

string

Indicates whether the shipment should be confirmed and created immediately.

Enum: "Y" "N"

Example: Y

pickup_arrange

json-string

Optional pickup window details for local shipments.

pickup_date

string

Pickup date.

Required when any pickup arrange field is present. Format: YYYY-MM-DD.

Example: 2026-02-26

pickup_start_time

string

Pickup window start time.

Format: HH:MM, between 09:30 and 18:00.

Example: 09:30

pickup_end_time

string

Pickup window end time.

Format: HH:MM, between 12:00 and 20:30 and at least 150 minutes after pickup_start_time.

Example: 18:00

Example request body

{
  "ship_type": "local",
  "sender": {
    "name": "Fuuffy Chai",
    "mobile": "64105317",
    "mobile_prefix": "852",
    "email": "cs@fuuffy.com",
    "address": "Rm2211, 9 Chong Yip Street, Ngau Tau Kok, Hong Kong"
  },
  "recipient": {
    "name": "小編姐姐",
    "mobile": "64105317",
    "mobile_prefix": "852",
    "email": "cs@fuuffy.com",
    "address": "香港九龍牛頭角創業街9號2211室"
  },
  "shipment_detail": {
    "package_type": "parcel",
    "consignment_declaration": "Toys",
    "parcel_list": [
      {
        "act_weight": "0.5",
        "height": "10",
        "width": "14",
        "length": "23",
        "parcel_items": [
          {
            "name": "Toy",
            "qty": "1",
            "single_value": "200.00",
            "sku": "SKU-001",
            "bar_code_eid": "1234567890",
            "is_pre_order": "N"
          }
        ],
        "insurance_fee": "0"
      }
    ]
  },
  "shipping_provider": "sf_expresshk_local",
  "client_remarks": "#5493979",
  "is_local_insurance": "N",
  "cod": "N",
  "cod_amount": "",
  "delivery_proof": "N",
  "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": "local",
  "shipping_provider": "sf_expresshk_local",
  "sender": { "name": "Fuuffy Chai", "mobile": "64105317", "mobile_prefix": "852", "email": "cs@fuuffy.com", "address": "Rm2211, 9 Chong Yip Street, Ngau Tau Kok, Hong Kong" },
  "recipient": { "name": "小編姐姐", "mobile": "64105317", "mobile_prefix": "852", "email": "cs@fuuffy.com", "address": "香港九龍牛頭角創業街9號2211室" },
  "shipment_detail": {
    "package_type": "parcel",
    "consignment_declaration": "Toys",
    "parcel_list": [{ "act_weight": "0.5", "length": "23", "width": "14", "height": "10", "parcel_items": [{ "name": "Toy", "qty": "1", "single_value": "200.00", "sku": "SKU-001", "bar_code_eid": "1234567890", "is_pre_order": "N" }], "insurance_fee": "0" }]
  },
  "client_remarks": "#5493979",
  "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: 3550646

ship_type

string

Shipping type for this order.

Example: local

order_status

string

Order status.

Example: READY_TO_SHIP

quote_price

string

Quoted shipping price in HKD.

Example: 28.50

confirm_shipment

string

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

tracking_number

string | null

Tracking number when confirmed.

client_remarks

string | null

Client notes for the order.

create_time

string

Order creation timestamp (ISO 8601).

Example: 2025-12-09T17:38:46+08:00

message

string

Human-readable status message.

Response sample

{
  "data": {
    "order_id": "3550646",
    "ship_type": "local",
    "order_status": "READY_TO_SHIP",
    "quote_price": "28.50",
    "confirm_shipment": "Y",
    "tracking_number": "SF7444700459388",
    "client_remarks": "#5493979",
    "create_time": "2025-12-09T17:38:46+08:00",
    "message": "confirmed and assigned with a tracking number"
  }
}

400 Bad Request

Response schema: application/json

error.code

string

Error code returned by the API.

Example: 400000

error.code_reason

string

Machine-readable error reason.

Example: BAD_REQUEST

error.message

string

Summary of the error.

Example: Bad Request

error.error_trace

array

List of validation errors.

field

string

Request field that failed.

Example: sender.mobile

code

string

Error code for this validation error.

Example: 400421

message

string

Human-readable explanation for this error.

Example: sender mobile is required and must be valid

Response sample with multiple validation errors

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      { "field": "sender.phone", "message": "Phone number is required" },
      { "field": "package.weight", "message": "Weight must be greater than 0" }
    ]
  }
}

Response sample with single validation error example

{
  "error": {
    "code": "400000",
    "code_reason": "BAD_REQUEST",
    "message": "Bad Request",
    "error_trace": [
      { "field": "json_parse", "message": "Invalid JSON format" }
    ]
  }
}

401 Unauthorized

Response schema: application/json

code

string

Error code returned by the API.

Example: 401000

code_reason

string

Machine-readable reason.

Example: UNAUTHORIZED

message

string

Human-readable message.

Example: Unauthorized

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

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

Response sample with single validation error example​

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

Response sample with single validation error example

401 Unauthorized

403 Forbidden

404 Not Found

500 Failure