API Documentation

📘 中文版

API documentation:

1. Authenticate with the vendor-token request header; please contact your business manager.

2. Use the API domain; please contact your business manager.

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)
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;
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