📦 Order API Documentation

rate (Get Rate) / print (Create Order) / cancel (Cancel Order) / label (Get Label) / tracking (Get Tracking)

Table of Contents

  1. 1. Overview (Method / Authentication / Response / Status Codes)
  2. 2. rate - Get Rate
  3. 3. print - Create Order (contains all rate parameters)
  4. 4. cancel - Cancel Order
  5. 5. label - Get Label
  6. 6. tracking - Get Tracking
  7. 7. scan-form - Batch Scan Form
  8. 8. Common Parameters (Address / Package) & Error Messages

1. Overview

The following conventions apply to all endpoints.

Method & URL

POST  /api/order/<action>
Parameter Description
action Endpoint name: rate / print / cancel / label / tracking / scan-form
Content-Type application/x-www-form-urlencoded and application/json are both supported

Authentication

Request Header: Every request must carry the vendor-token header, whose value is the token field of the vendor (customer) table.
If the token is missing, invalid, or the vendor is disabled, the API returns code = 100 and you need to log in again.
Header Required Description
vendor-token Yes Vendor login token (the token field of the vendor table)

Response Structure

{
    "success": true,   // true=success false=failure
    "message": "Success message",
    "msg":      "Success message",   // Same as message
    "code":    200,      // 200=success 400=failure 100=login required
    "data":    {}                     // Business data; empty array on failure
}

Status Codes

code Meaning Description
200 Success success = true, business data is in data
400 Failure success = false, error message is in message / msg
100 Login expired Token missing / vendor not found / disabled / session expired; please obtain a new token

POST rate - Get Rate

URL: /api/order/rate　·　Description: Query shipping rates from available carriers. No database record is created and no charge is made.

Parameters

Key rules: ① shipping_code and shipping_service are optional — if omitted, rates for ALL available channels of the vendor are returned (multiple channels are quoted in parallel; a failure of one channel does not affect the others); if provided, only that channel is quoted. ② When a channel is specified, both shipping_code and shipping_service must be passed together.
Parameter Required Type Description
shipping_code Optional string Channel code (e.g. iusps / fdx / ups / dhl / arm); omit to quote all channels
shipping_service Optional string Channel service code (e.g. zdgj / fdxp / iups); must be passed with shipping_code
reference Optional string Order reference number (only recorded during rate, uniqueness is not checked)
ship_date Optional string Ship date in YYYY-MM-DD format; only supported by some channel services, and must be within the next 7 days. When empty the channel uses its default (some channels +2 days)
is_signature Optional int Signature service 0/1, default 0
is_insurances Optional int Insurance 0/1, default 0
unit Optional int Unit system, default 1 (metric)
currency Optional string Currency, default 1 (USD)
Shipper address (pass the fields directly, or pass only vendor_address_id and the system loads the saved address)
shipper_name … shipper_zipcode Optional string Shipper fields, see common parameter table
vendor_address_id Optional int ID of a saved shipper address; takes priority when passed
vendor_address_label Optional string User address label (address code / label of a saved shipper address); both this and vendor_address_id are optional and may be passed independently or together to specify a saved address, priority id > label
Recipient address (the following 4 fields are required)
recipient_name Yes string Recipient name
recipient_street1 Yes string Recipient address - street 1
recipient_city Yes string Recipient city
recipient_country Yes string Recipient country (e.g. US)
Other recipient_* Optional string See common parameter table
Package info (packages array format)
packages Yes* array Array of packages, fields see package parameter table; recommended
length/width/height/weight Yes* number pass the four dimension/weight fields directly
weight_unit Yes* string Weight unit: lb / g / kg / oz (invalid value returns an error)
length_unit Yes* string Length unit: in / cm / m (invalid value returns an error)
Required constraints: at least one package must be provided (length/width/height/weight all required); the 4 recipient fields are required.

Request Example

# Quote all channels (omit channel parameters)
POST /api/order/rate
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "shipper_name": "John",
    "shipper_street1": "123 Main St",
    "shipper_city": "Los Angeles",
    "shipper_state": "CA",
    "shipper_country": "US",
    "shipper_zipcode": "90001",
    "recipient_name": "Jane",
    "recipient_street1": "456 Oak Ave",
    "recipient_city": "New York",
    "recipient_state": "NY",
    "recipient_country": "US",
    "recipient_zipcode": "10001",
    "packages": [
        {
            "name": "dress",
            "length": 12,
            "width": 10,
            "height": 5,
            "weight": 3.3,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

Response Example (data is an array of channel quotes)

{
    "success": true,
    "message": "Price fetched successfully!",
    "code": 200,
    "data": [
        {
            "success": true,
            "message": "success",
            "fee": 15.05,          // Shipping fee
            "zone": "zone8",           // Zone
            "billing_weight": 3.3069,   // Billing weight (lb)
            "weight_g": 1499,          // Weight (g)
            "currency_id": 1,            // Currency: 1=USD
            "shipping_service": "zdgj", // Channel service code
            "shipping_code": "iusps",   // Channel code
            "carrier_name": "USPS",     // Carrier name
            "carrier_code": "usps",     // Carrier code
            "carrier_logo": "https://.../usps.png", // Carrier logo
            "content": null
        }, // ... other channels
        {
            "success": false,       // A single failed channel does not affect the whole result
            "message": "This channel does not support shipping to the destination area, please choose another channel",
            "shipping_service": "fdx",
            "shipping_code": "iexp2",
            "carrier_name": "FedEx",
            "carrier_code": "fedex",
            "carrier_logo": "https://.../fedex.png",
            "content": null
        }
    ]
}
data[] field Type Description
success bool Whether this channel quoted successfully; when false, message is the failure reason and the carrier fields are still returned
message string success on success / failure reason
fee number Final shipping fee (includes markup / surcharges)
zone string Zone (e.g. zone8)
billing_weight number Billing weight (lb)
weight_g int Weight (grams)
currency_id int Currency ID, default 1 (USD)
shipping_service / shipping_code string Channel service code / Channel code
carrier_name / carrier_code / carrier_logo string Carrier name / code / logo
content null Order content placeholder (used when a channel combines order creation and rate), currently null

POST print - Create Order / Print Label

URL: /api/order/print　·　Description: Validate balance → save order → create order at the channel → get label → deduct fee. Returns the order info and the label URL.

âš  Important: print contains ALL parameters of rate (address / package / unit / extra services are identical), and adds the following required parameters on top of rate: shipping_code, shipping_service.

Parameters (= all rate parameters + the following additions / required)

Parameter Required Type Description
shipping_code Yes string Channel code (optional in rate, required in print)
shipping_service Yes string Channel service code (optional in rate, required in print)
reference Optional string Order reference; an existing reference cannot be used again (returns "Reference already exists!")
remark Optional string Order remark
label_type Optional string Label type; only supported by some channels / interfaces, omitted means the channel default format is returned.
Allowed values: PDF / ZPL / ZPL203DPI (any value outside this set returns a parameter error)
All other parameters (shipper / recipient / package / ship_date / unit / currency / is_signature / is_insurances / vendor_address_id / vendor_address_label) are identical to rate with the same required rules. See the rate parameter table and common parameters.
Order flow notes: â‘  Before creating the order, the vendor balance + credit must be > 0 (otherwise "Insufficient vendor balance, please top up first!" is returned). â‘¡ After the channel creates the order successfully: order status is set to printed + paid, balance is deducted, transaction detail and order price info are written (in one transaction). â‘¢ When the channel does not return a label synchronously, the system polls get_label (up to 1200 seconds); on final failure the order is set to printed + unpaid and the request fails. â‘£ On channel order failure the error message is recorded into the error-deal table; if an English error text is configured, the English text is returned.

Request Example (includes all rate parameters)

# Compared with rate, only the required channel parameters + reference/remark are added
POST /api/order/print
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "shipping_code": "iusps",
    "shipping_service": "zdgj",
    "reference": "ORDER-20260921-001",
    "remark": "please handle carefully",
    "label_type": "PDF", // Optional: label type (PDF / ZPL / ZPL203DPI), only supported by some channels
    "ship_date": "2026-09-21",
    "is_signature": 0,
    "is_insurances": 0,
    "shipper_name": "John",
    "shipper_company": "Piggyship",
    "shipper_telphone": "+1 213 555 0100",
    "shipper_street1": "123 Main St",
    "shipper_city": "Los Angeles",
    "shipper_state": "CA",
    "shipper_country": "US",
    "shipper_zipcode": "90001",
    "recipient_name": "Jane",
    "recipient_company": "ABC Inc",
    "recipient_telphone": "+1 212 555 0199",
    "recipient_street1": "456 Oak Ave",
    "recipient_city": "New York",
    "recipient_state": "NY",
    "recipient_country": "US",
    "recipient_zipcode": "10001",
    "packages": [
        {
            "name": "dress",
            "length": 12,
            "width": 10,
            "height": 5,
            "weight": 3.3,
            "weight_unit": "lb",
            "length_unit": "in"
        }
    ]
}

Response Example (data is the order result)

{
    "success": true,
    "message": "Order created successfully!",
    "code": 200,
    "data": {
        "success": true,
        "message": "success",
        "fee": 15.05,            // Deducted amount
        "zone": "zone8",
        "billing_weight": 3.3069,
        "currency_id": 1,
        "order_id": 1024,            // System order ID
        "label": "https://cdn.xxx.com/label/123_1699999999.pdf", // Label URL (Qiniu CDN)
        "tracking": "20260921153000_ab12cd", // System order number (note: NOT the label number)
        "ext_tracking": "9212345678901234567890", // Channel tracking/label number
        "fee_detail": [{"code": "shipping_fee","name": "Shipping Fee","amount": 15.05}]   // Fee detail list
    }
}
data field Type Description
order_id int System order ID
fee / zone / billing_weight / currency_id - Fee / Zone / Billing weight / Currency
label string Label PDF URL (Qiniu CDN), can be downloaded and printed directly
tracking string System order number (generated as timestamp + random string), used as the order receipt number
ext_tracking string Channel tracking/label number (used to query tracking)
fee_detail array List of fee details

POST cancel - Cancel Order

URL: /api/order/cancel　·　Description: Cancel an order and refund the balance (supports frozen-period refunds and processing-fee deduction).

Parameters

Parameter Required Type Description
order_id Yes int Order ID (only the current vendor's own orders can be operated)
Cancel rules: â‘  A completed order cannot be canceled; an already canceled order cannot be canceled again. â‘¡ When the channel has frozen_day configured, the refund goes to the frozen balance; otherwise it goes directly to the available balance. â‘¢ The refund deducts the service's refund_price processing fee ratio. â‘£ Orders in pending (status=0) state do not call the channel cancel API; only the local refund is performed.

Request Example

POST /api/order/cancel
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "order_id": 1024
}

Response Example

{
    "success": true,
    "message": "Order canceled successfully!",
    "msg": "Order canceled successfully!",
    "code": 200,
    "data": []     // data is an empty array on success
}

POST label - Get Label

URL: /api/order/label　·　Description: Get the label of an order (if the label was already generated synchronously when creating the order, you can directly use the label returned by print).

Parameters

Parameter Required Type Description
order_id Yes int Order ID (only the current vendor's own orders can be operated)

Request Example

POST /api/order/label
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "order_id": 1024
}

Response Example (data is the unified channel return structure)

{
    "success": true,
    "message": "Label fetched successfully!",
    "code": 200,
    "data": {
        "success": true,
        "currency_id": 1,
        "label": "https://cdn.xxx.com/label/123_1699999999.pdf",  // Label URL
        "tracking": "9212345678901234567890",      // Channel tracking number
        "sub_labels": []                                       // Per-piece labels for multi-piece shipments (currently empty)
    }
}

POST tracking - Get Tracking

URL: /api/order/tracking　·　Description: Get the logistics tracking of an order (calls the channel's get_tracking).

Parameters

Parameter Required Type Description
order_id Yes int Order ID (only the current vendor's own orders can be operated)

Request Example

POST /api/order/tracking
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "order_id": 1024
}

Response Example (data is the channel's unified structure)

{
    "success": true,
    "message": "Tracking retrieved successfully!",
    "code": 200,
    "data": {
        "trackingNumber": "9212345678901234567890",   // Tracking number
        "status": "delivered",                 // Tracking status
        "statusCategory": "delivered",           // Status category
        "serviceTypeCode": "144",               // STC code
        "originCity": "LOS ANGELES",
        "originState": "CA",
        "originZIP": "90001",
        "destinationCity": "NEW YORK",
        "destinationState": "NY",
        "destinationZIP": "10001",
        "trackingEvents": [{
            "eventType": "Delivered, Left with Individual",
            "eventTimestamp": "2026-10-01T11:04:19",
            "eventCountry": "US",
            "eventCity": "DES PLAINES",
            "eventState": "IL",
            "eventZIP": "60016",
            "location": "DES PLAINES,IL,60016",
            "timeZone": "GMT-05:00",
            "eventCode": "01",
            "GMTTimestamp": "2026-10-01T16:04:19Z"
        }]
    }
}

data Field Reference

data field Type Description
trackingNumber string Tracking number
status / statusCategory string Tracking status / channel status category (e.g. delivered)
serviceTypeCode string STC code
origin* / destination* string Origin / destination city, state code, ZIP
trackingEvents array List of tracking events; each item has eventType / eventTimestamp / eventCountry / eventCity / eventState / eventZIP / location / timeZone / eventCode / GMTTimestamp

POST scan-form - Batch Scan Form

URL: /api/order/scan-form　·　Description: Aggregate the tracking numbers of a batch of "printed" orders under the same channel into one scan form (e.g. a USPS Scan Form) so they can be scanned into the network in a single pass. Only channels that implement scanForm are supported (other channels return a clear error).

Usage conditions:
  1. Only some channel services support this endpoint. Please consult your account manager to confirm availability.
  2. The ship_date of the associated orders must be a date after today (i.e. later than the current date, today excluded).

Parameters

Parameter Required Type Description
order_id One of two array / string List of order IDs. Mutually exclusive with order_no (pass one or the other). The value may be an array, or a string separated by semicolons (;) (the backend also tolerates comma / newline / whitespace separators). Pure-integer values are queried as order_id and only "printed" orders belonging to the current vendor are valid.
order_no One of two array / string List of order numbers. Mutually exclusive with order_id (pass one or the other). Same value and separator rules as above; non-integer values are queried as order_no.

Request Example

POST /api/order/scan-form
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "order_id": [1024, 1025, 1026]
}
POST /api/order/scan-form
Header: vendor-token: xxxxx
Content-Type: application/json
{
    "order_no": "AB20240101;AB20240102;AB20240103"
}

Response Example (data is the channel's unified structure)

{
    "success": true,
    "message": "Batch scan form created successfully!",
    "code": 200,
    "data": {
        "scanFormNo": "SF1234567890",   // Scan form number
        "scanFormLabel": "https://cdn.example.com/scanform/SF1234567890.pdf"  // Scan form label URL
    }
}

8. Common Parameters (Address / Package) & Error Messages

rate and print share the following address and package parameters.

Shipper address parameters (shipper_*, optional; may pass vendor_address_id / vendor_address_label instead)

Parameter Description
shipper_name Shipper name
shipper_company Shipper company
shipper_telphone Contact phone
shipper_email Email
shipper_country Country (e.g. US)
shipper_state State / Province
shipper_city City
shipper_street1 / shipper_street2 Street address 1 / 2
shipper_zipcode Postal code / ZIP

Recipient address parameters (recipient_*)

Parameter Required Description
recipient_name Yes Recipient name
recipient_street1 Yes Street address 1
recipient_city Yes City
recipient_country Yes Country (e.g. US)
recipient_company Optional Recipient company
recipient_street2 Optional Street address 2
recipient_zipcode Optional Postal code / ZIP
recipient_state Optional State / Province
recipient_email Optional Email
recipient_telphone Optional Contact phone

Package parameters (packages array, shared by rate/print)

Parameter Required Description
packages[i].name Optional Package name / item name
packages[i].length Yes Length
packages[i].width Yes Width
packages[i].height Yes Height
packages[i].weight Yes Weight
packages[i].weight_unit Yes Weight unit: lb/g/kg/oz
packages[i].length_unit Yes Length unit: in/cm/m
packages[i].unit Optional Unit system, default 1 (metric)

Error Messages Quick Reference (code=400, returned in message/msg)

Endpoint Error Message Description
Common Please provide the vendor ID! Vendor ID is missing
Common Please provide the package info! No package info was passed
Common Package N: dimensions and weight are incomplete! Package N has incomplete dimensions/weight
Common Package N: invalid weight unit, only lb/g/kg/oz are supported! Package N has an invalid weight unit
Common Package N: invalid length unit, only in/cm/m are supported! Package N has an invalid length unit
Common Invalid weight unit / Invalid length unit, ... Invalid unit in the legacy single-package format
Common Please provide the complete recipient address! Recipient address is incomplete (name/street1/city/country)
print Please provide the shipping code! Channel code is missing for order creation
print Please provide the shipping service code! Channel service code is missing for order creation
print Insufficient vendor balance, please top up first! Balance + credit ≤ 0, please top up first
print Reference already exists! Reference is duplicated; the order cannot be created again
print Carrier not found Carrier does not exist
print Label fetch timeout: waiting 1200s, ... Label fetch timed out
cancel Please provide the order ID! Order ID is missing
cancel Order not found! Order does not exist, or is not owned by the current vendor (ownership check failure returns the same message)
cancel Order already completed, cannot be canceled! The order is completed and cannot be canceled
cancel Order already canceled, do not repeat! The order is already canceled; do not repeat the operation
cancel Service not found for this order! The service for this order does not exist
label Shipping not found for this order! The channel for this order does not exist
label Label data is empty / Response missing base64code The channel did not return label data
Common Channel passthrough errors (msgEn/Msg) Error messages returned by the channel API are returned as-is