Logistics Order API
Ocean FCL/LCL, air, express and FBA use the website customer-center workflows. Create orders, query your order details and receivable bills, and update or void orders when their status allows. Booking and document issuance follow normal operations.
Orders belong to the website customer linked to the AppKey developer. That customer must complete personal or business verification; request parameters cannot choose another owner or salesperson.
Customer References and Retries#
client_order_no is unique per customer and order type, across that customer’s apps. Retrying the same effective payload returns the original order with replayed=true. Reusing it with a different payload returns HTTP 409 / code 1003. Each retry needs a new timestamp and nonce; retain the reference and order payload. After a timeout, query by reference before retrying.
Common Parameters#
Use application/json for POST requests and URL query parameters for the options GET endpoint. Sign requests as described in Authentication. Create/update/cancel bodies are limited to 256KB; each item list is limited to 200 rows. Numeric fields, including item fields, are in 0–100000000, with positive/integer requirements as specified below. Strings are generally limited to 255 characters; exceptions are stated explicitly.
Check the common fields and your order-type table. Yes means required; conditional fields are required when the stated condition applies. Fields with defaults may be omitted; an empty string is validated by the field rules and is different from omission. Inline contacts require company, contact, tel and address. Missing or invalid fields are returned together in one response.
| Field | Type | Required | Description |
|---|---|---|---|
| client_order_no | string | Yes | Your order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup. |
| goods_type | string | Yes | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| goods_pcs | integer | Yes | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| goods_pcs_unit | string | No | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| goods_weight | number | Yes | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| goods_cbm | number | Required for ocean / FBA | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| custom | object | No | Customs service; optional. See Additional services for its fields. |
| insurance | object | No | Insurance service; optional. See Additional services for its fields. |
| collecting | array<object> | No | Inbound collection shipments, default [], up to 200 items; see Additional services. |
| packup | array<object> | No | Pickup arrangements, default [], up to 200 items; see Additional services. |
| note | string | No | Customer instructions; defaults to an empty string, up to 255 characters. |
Ocean (FCL / LCL)#
/api/openapi/v1/orders/ocean/createSupports FCL and LCL. All public top-level request fields are listed below; packing[] contains container details.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| client_order_no | string | Yes | Your order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup. |
| goods_type | string | Yes | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| goods_pcs | integer | Yes | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| goods_pcs_unit | string | No | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| goods_weight | number | Yes | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| goods_cbm | number | Required for ocean / FBA | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| custom | object | No | Customs service; optional. See Additional services for its fields. |
| insurance | object | No | Insurance service; optional. See Additional services for its fields. |
| collecting | array<object> | No | Inbound collection shipments, default [], up to 200 items; see Additional services. |
| packup | array<object> | No | Pickup arrangements, default [], up to 200 items; see Additional services. |
| note | string | No | Customer instructions; defaults to an empty string, up to 255 characters. |
| pol | string | Yes | Origin port internal code, e.g. CNSHA. Use the port dictionary code, not locode. |
| pod | string | Yes | Destination port internal code, e.g. USLSA; must differ from pol. |
| carrier | string | No | Carrier internal code from the carrier dictionary; defaults to an empty string. |
| etc | string | No | Expected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string. |
| mx | integer | No | Trade direction: 1 import, 2 export (default). |
| transport_type | string | No | Transport type, default fcl; use lcl for LCL. See transport_types[].value for available values. fcl/fob require container details. |
| shipping_mode | string | Yes | Shipping terms from shipping_modes[].value, e.g. CY-CY. |
| goods_marks | string | Yes | Shipping marks, up to 4000 characters. |
| goods | string | Yes | Cargo name/description, up to 4000 characters; this field is text. |
| sender | integer | object | Yes | Shipper: your contact ID or a complete contact object; see Contacts. |
| consignee | integer | object | Yes | Consignee: your contact ID or a complete contact object; see Contacts. |
| notifier | integer | object | Yes | Notify party: your contact ID or a complete contact object; see Contacts. |
| packing | array<object> | Required for fcl / fob | Container details, up to 200 items. Cannot be empty for FCL; optional for LCL. Item fields are listed below. |
| blt | integer | No | Bill of lading type from bill_types[].value, 0–3; default 0. |
| payment | integer | No | Freight payment terms: 0 prepaid (default), 1 collect. This is not the bill payment status. |
packing[] container and cargo fields#
[] denotes one array item. Required item fields apply when that item is submitted; up to 200 items per list.
| Field | Type | Required | Description |
|---|---|---|---|
| packing[].ctn_no | string | No | Container number, up to 255 characters. |
| packing[].ctt | string | Yes | Container size from container_sizes[].value, e.g. 20GP; each submitted item must use a valid size. |
| packing[].seal_no | string | No | Seal number, up to 255 characters. |
| packing[].ctn_num | number | Required for fcl / fob | Container count; a positive integer is required for fcl/fob. |
| packing[].qty | number | No | Cargo quantity for this row, non-negative. |
| packing[].qty_unit | string | No | Packaging unit for this row, e.g. CTN. |
| packing[].wgt | number | No | Total cargo weight for this row in kg; top-level goods_weight must still be supplied. |
| packing[].vol | number | No | Total cargo volume for this row in m³; top-level goods_cbm must still be supplied. |
Example Request (Replace Option Values Before Submitting)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pol": "CNSHA",
"pod": "USLSA",
"transport_type": "fcl",
"shipping_mode": "CY-CY",
"goods": "General cargo",
"goods_marks": "MY-MARKS",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"packing": [
{
"ctt": "20GP",
"ctn_num": 1
}
]
}Air#
/api/openapi/v1/orders/air/createAll public top-level request fields are listed below. goods_list[] holds cargo rows; supply shipment totals at the top level.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| client_order_no | string | Yes | Your order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup. |
| goods_type | string | Yes | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| goods_pcs | integer | Yes | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| goods_pcs_unit | string | No | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| goods_weight | number | Yes | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| goods_cbm | number | Required for ocean / FBA | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| custom | object | No | Customs service; optional. See Additional services for its fields. |
| insurance | object | No | Insurance service; optional. See Additional services for its fields. |
| collecting | array<object> | No | Inbound collection shipments, default [], up to 200 items; see Additional services. |
| packup | array<object> | No | Pickup arrangements, default [], up to 200 items; see Additional services. |
| note | string | No | Customer instructions; defaults to an empty string, up to 255 characters. |
| pol | string | Yes | Origin airport IATA code, e.g. PVG. |
| pod | string | Yes | Destination airport IATA code, e.g. LAX; must differ from pol. |
| airline | string | No | Airline internal code or IATA code from the airline dictionary; defaults to an empty string. |
| etc | string | No | Expected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string. |
| mx | integer | No | Trade direction: 1 import, 2 export (default). |
| transport_type | string | No | Air service: regular (default), consol (consolidation), or chartered. |
| air_mode | integer | No | Service terms: 0 airport-to-airport (default), 1 DDU, 2 DDP, 3 DAP, 4 customs clearance at both ends. |
| goods_marks | string | No | Shipping marks; defaults to an empty string, up to 255 characters. |
| goods | string | Yes | Cargo name/description, up to 255 characters; this field is text. |
| sender | integer | object | Yes | Shipper: your contact ID or a complete contact object; see Contacts. |
| consignee | integer | object | Yes | Consignee: your contact ID or a complete contact object; see Contacts. |
| notifier | integer | object | Yes | Notify party: your contact ID or a complete contact object; see Contacts. |
| goods_list | array<object> | No | Cargo rows, default [], up to 200 items; see the item fields below. |
goods_list[] air cargo fields#
[] denotes one array item. Required item fields apply when that item is submitted; up to 200 items per list.
| Field | Type | Required | Description |
|---|---|---|---|
| goods_list[].goods | string | No | Cargo name for this row, up to 255 characters. |
| goods_list[].goods_packing | string | No | Packaging unit for this row, e.g. CTN. |
| goods_list[].goods_pcs | number | No | Package count for this row, non-negative. |
| goods_list[].goods_weight | number | No | Total weight for this row in kg. |
| goods_list[].goods_length | number | No | Length of one package in cm. |
| goods_list[].goods_width | number | No | Width of one package in cm. |
| goods_list[].goods_height | number | No | Height of one package in cm. |
| goods_list[].goods_cbm | number | No | Total volume for this row in m³. The API does not derive it from dimensions; submit the actual total. |
Example Request (Replace Option Values Before Submitting)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pol": "PVG",
"pod": "LAX",
"goods": "General cargo",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods_list": [
{
"goods_packing": "CTN",
"goods_pcs": 2,
"goods_weight": 20,
"goods_length": 50,
"goods_width": 50,
"goods_height": 100
}
]
}Express#
/api/openapi/v1/orders/express/createTop-level goods_pcs is the package count and goods_weight is the total shipment weight. goods[] holds declared products. This endpoint accepts a consignee and notify party; it has no shipper field.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| client_order_no | string | Yes | Your order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup. |
| goods_type | string | Yes | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| goods_pcs | integer | Yes | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| goods_pcs_unit | string | No | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| goods_weight | number | Yes | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| goods_cbm | number | Required for ocean / FBA | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| custom | object | No | Customs service; optional. See Additional services for its fields. |
| insurance | object | No | Insurance service; optional. See Additional services for its fields. |
| collecting | array<object> | No | Inbound collection shipments, default [], up to 200 items; see Additional services. |
| packup | array<object> | No | Pickup arrangements, default [], up to 200 items; see Additional services. |
| note | string | No | Customer instructions; defaults to an empty string, up to 255 characters. |
| place_country | string | Yes | Two-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase. |
| channel | string | Yes | Express channel code from channels[].value in orders/options?order_type=express; must be an active express channel. |
| consignee | integer | object | Yes | Consignee: your contact ID or a complete contact object; see Contacts. |
| notifier | integer | object | Yes | Notify party: your contact ID or a complete contact object; see Contacts. |
| goods_cost | number | No | Total declared value: sum of calculated goods[].goods_cost. May be omitted; a valid but inconsistent supplied amount is replaced by the calculated amount. No items means 0; maximum 100000000. |
| cost_currency | string | No | Declaration currency, default USD, shared by product unit prices, row values and shipment total. |
| fare_declare | number | No | Declared freight charge, non-negative; default 0, maximum 100000000. |
| goods | array<object> | No | Declared products, default [], up to 200 items. Each goods_cost is calculated as goods_pcs × goods_price, rounded to two decimals, then summed into the shipment value. Omitted quantity or price means 0. Package counts and weights are independent. |
goods[] express declaration fields#
[] denotes one array item. Required item fields apply when that item is submitted; up to 200 items per list.
| Field | Type | Required | Description |
|---|---|---|---|
| goods[].goods_chs | string | No | Chinese product name, up to 255 characters. |
| goods[].goods_en | string | No | English product name, up to 255 characters. |
| goods[].goods_pcs | number | No | Product quantity for this row, not carton count. For two products in one carton, use 2. Omitted quantity means 0 for value calculation. |
| goods[].goods_price | number | No | Unit price per product in the top-level cost_currency; omitted price means 0. |
| goods[].goods_cost | number | No | Row value, automatically calculated as quantity × unit price and rounded to two decimals; may be omitted. Maximum 100000000. Negative or invalid supplied values still fail validation. |
| goods[].goods_hscode | string | No | Product HS code; submit a string to preserve leading zeros, up to 255 characters. |
| goods[].goods_use | string | No | Product use, up to 255 characters. |
| goods[].goods_material | string | No | Product material, up to 255 characters. |
| goods[].goods_thumb | string | No | Product image URL, up to 255 characters; this is not a binary or Base64 upload field. |
Example Request (Replace Option Values Before Submitting)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 1,
"goods_pcs_unit": "CTN",
"goods_weight": 5,
"goods_cbm": 0.02,
"goods_cost": 20,
"cost_currency": "USD",
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"place_country": "US",
"channel": "YOUR_EXP_CHANNEL",
"consignee": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"notifier": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods": [
{
"goods_chs": "示例商品",
"goods_en": "Sample goods",
"goods_pcs": 2,
"goods_price": 10,
"goods_cost": 20
}
]
}FBA / Dedicated line#
/api/openapi/v1/orders/fba/createFBA warehouse and dedicated-line shipments share this endpoint, selected by fba_type. Supply SKU values and shipment totals separately; the express value recalculation rule does not apply.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| client_order_no | string | Yes | Your order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup. |
| goods_type | string | Yes | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| goods_pcs | integer | Yes | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| goods_pcs_unit | string | No | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| goods_weight | number | Yes | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| goods_cbm | number | Required for ocean / FBA | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| custom | object | No | Customs service; optional. See Additional services for its fields. |
| insurance | object | No | Insurance service; optional. See Additional services for its fields. |
| collecting | array<object> | No | Inbound collection shipments, default [], up to 200 items; see Additional services. |
| packup | array<object> | No | Pickup arrangements, default [], up to 200 items; see Additional services. |
| note | string | No | Customer instructions; defaults to an empty string, up to 255 characters. |
| pod | string | Yes | Two-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase. |
| channel | string | Yes | FBA/dedicated-line channel code from channels[].value in orders/options?order_type=fba. |
| fba_type | integer | No | Shipment type: 0 FBA warehouse (default), 1 dedicated line. |
| transport | integer | No | Transport: 0 ocean, 1 air (default), 2 rail, 3 truck. |
| fba | string | Required if fba_type = 0 | FBA warehouse code from fba_warehouses[].value; must match pod. The warehouse consignee is generated automatically. |
| shipment_id | string | Required if fba_type = 0 | Amazon Shipment ID, up to 255 characters. |
| amazon_reference_id | string | Required if fba_type = 0 | Amazon Reference ID, up to 255 characters. |
| sender | integer | object | No | Shipper, optional: your contact ID or a complete contact object; see Contacts. |
| consignee | integer | object | Required if fba_type = 1 | Dedicated-line consignee; generated from the warehouse for FBA shipments: your contact ID or a complete contact object; see Contacts. |
| pot | string | No | Transit location; defaults to an empty string, up to 255 characters. |
| goods_cost | number | No | Shipment value, non-negative; default 0, maximum 100000000. Sum goods[].sku_amount before submitting. |
| goods | array<object> | No | SKU rows, default [], up to 200 items; see below. |
goods[] FBA / dedicated-line SKU fields#
[] denotes one array item. Required item fields apply when that item is submitted; up to 200 items per list.
| Field | Type | Required | Description |
|---|---|---|---|
| goods[].sku_no | string | No | SKU reference, up to 255 characters. |
| goods[].sku_packing | string | No | Packaging unit, e.g. CTN. |
| goods[].sku_box_number | string | No | Carton number or range, up to 255 characters. |
| goods[].sku_nw | number | No | Net weight per carton in kg. |
| goods[].sku_gw | number | No | Gross weight per carton in kg; row gross weight = sku_ctns × sku_gw. |
| goods[].sku_length | number | No | Carton length in cm. |
| goods[].sku_width | number | No | Carton width in cm. |
| goods[].sku_height | number | No | Carton height in cm. |
| goods[].sku_ctns | number | No | Carton count for this SKU, non-negative. |
| goods[].sku_pcs | number | No | Total product quantity for this SKU, not quantity per carton; used with unit price to calculate row value. |
| goods[].sku_price | number | No | Product unit price; the website uses USD. |
| goods[].sku_amount | number | No | Row value; calculate sku_pcs × sku_price before submitting. The website uses USD. |
| goods[].sku_vol | number | No | Total row volume in m³; calculate sku_ctns × length × width × height ÷ 1000000 before submitting. |
| goods[].sku_weight | number | No | Total gross weight for this row in kg; calculate sku_ctns × sku_gw before submitting. |
Example Request (Replace Option Values Before Submitting)#
{
"client_order_no": "MY-ORDER-001",
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"custom": {
"custom": 0
},
"insurance": {
"is_buy": 0
},
"pod": "US",
"channel": "YOUR_FBA_CHANNEL",
"fba_type": 0,
"transport": 0,
"fba": "ONT8",
"shipment_id": "YOUR_SHIPMENT_ID",
"amazon_reference_id": "YOUR_AMAZON_REFERENCE",
"sender": {
"company": "Example Company",
"contact": "Contact Name",
"tel": "+1-555-0100",
"address": "Replace with actual address"
},
"goods": [
{
"sku_no": "SKU-001",
"sku_packing": "CTN",
"sku_ctns": 2,
"sku_pcs": 10,
"sku_gw": 10,
"sku_nw": 9
}
]
}Contact objects#
See each creation table for supported roles: sender, consignee and notifier. Each accepts your contact ID or the complete object below. Four object fields are required; submitted objects are saved as your contacts. Another customer’s contact ID is not accepted. Express has only consignee and notifier; put its country in top-level place_country, state/city in address, and postal code in post.
Internal fields such as id and auth are not accepted in contact objects. Send either a contact ID or an object. Objects must contain company, contact, tel and address.
| Field | Type | Required | Description |
|---|---|---|---|
| company | string | Yes | Company/organization name, up to 255 characters. |
| contact | string | Yes | Contact person, up to 255 characters. |
| tel | string | Yes | Telephone number, preferably with international dialing code; up to 255 characters. |
| address | string | Yes | Full address including state/province, city and street, up to 4000 characters. No separate province/city fields are accepted. |
| string | No | Email address, up to 255 characters. | |
| post | string | No | Postal code; submit a string to preserve leading zeros, up to 255 characters. |
| duty | string | No | Tax ID, up to 255 characters. |
{
"consignee": {
"company": "Example Company",
"contact": "Jane Doe",
"tel": "+1-555-0100",
"address": "123 Example St, Los Angeles, CA, US",
"email": "[email protected]",
"post": "90001",
"duty": "YOUR_TAX_ID"
}
}Additional services#
All four creation endpoints accept these optional objects/lists. Omit a service when it is not needed. Updates replace the submitted object/list in full. Numeric item fields accept JSON numbers or numeric strings; numbers are recommended. Calculate fields yourself unless automatic calculation is explicitly documented.
custom customs service#
| Field | Type | Required | Description |
|---|---|---|---|
| custom.custom | integer | string | No | Customs type: 0 none, 1 general trade, 2 purchased-document declaration, 3 customer-managed. Ocean accepts comma-separated values such as "1,3"; other types accept one value. |
insurance service#
| Field | Type | Required | Description |
|---|---|---|---|
| insurance.is_buy | integer | No | Purchase insurance: 0 no, 1 yes. |
| insurance.money_type | string | No | Insurance currency, e.g. USD/CNY. |
| insurance.amount | number | No | Insured amount, non-negative, maximum 100000000. |
| insurance.beneficiary | string | No | Beneficiary, up to 100 characters. |
collecting[] inbound shipments#
| Field | Type | Required | Description |
|---|---|---|---|
| collecting[].company | string | No | Inbound courier company from express_companies[].value, up to 255 characters. |
| collecting[].number | string | No | Inbound tracking number, up to 255 characters. Normalized duplicates are rejected. Only your own or unassigned, unlinked warehouse records can be linked. |
| collecting[].note | string | No | Instructions for this inbound shipment, up to 255 characters. |
packup[] pickup arrangements#
| Field | Type | Required | Description |
|---|---|---|---|
| packup[].time | string | No | Requested pickup time; use YYYY-MM-DD HH:mm:ss, up to 255 characters. |
| packup[].address | string | No | Full pickup address, up to 4000 characters. |
| packup[].contact | string | No | Pickup contact, up to 255 characters. |
| packup[].tel | string | No | Pickup telephone number, up to 255 characters. |
Unified order response#
data includes order_id, order_no, order_type, client_order_no, work_no, status, status_name and replayed. hfs_no is returned only for express/FBA and omitted for ocean/air. New orders normally have status=0 (pending); binding received cargo may advance the status. Use order details for subsequent status.
Response envelope#
| Field | Type | Availability | Description |
|---|---|---|---|
| code | integer | Always | Business code: 0 for success; see error documentation for other values. |
| msg | string | Always | Result or error message. |
| request_id | string | Always | Request trace ID; retain it for support. |
| data | object | On success | Business result. Unless stated otherwise, the response field tables below are relative to data. |
| credit_used | integer | After quota processing | Credits used, 0 for order APIs. May be absent on early failures such as authentication errors. |
| credit_balance | integer | After quota processing | Remaining credits; -1 means unlimited. |
| quota | object | After quota processing | Credit information corresponding to credit_used and credit_balance. |
| quota.cost | integer | When quota is present | Credits used by this request, 0 for order APIs. |
| quota.remain | integer | When quota is present | Remaining credits; -1 means unlimited. |
Response fields (inside data)#
| Field | Type | Availability | Description |
|---|---|---|---|
| order_id | integer | Always | Platform order ID. |
| order_no | string | Always | System order number, also when the lookup used an Awice reference or work number. |
| order_type | string | Always | Order type: ocean, air, express, fba. |
| client_order_no | string | null | Always | External reference used in this request; null when operating by system order number without an external reference. |
| work_no | string | Always | Work number with an AW prefix; may be empty. Can be passed directly as order_no for detail lookup. |
| hfs_no | string | Express/FBA only; omitted for ocean/air | Awice reference: EV prefix for express, FV for FBA; may be empty. Can be passed directly as order_no for detail lookup. |
| status | integer | Always | Status: 0 pending, 1 pre-advised, 2 confirmed, 4 received, 5 shipped, 6 returned, 7 voided, 8 out of stock, 9 on hold. |
| status_name | string | Always | Current status label as returned by the server. |
| replayed | boolean | Always | True for a recognized repeat create/update/cancel request; false for detail and tracking. |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false
},
"credit_used": 0
}Order Options (Free)#
/api/openapi/v1/orders/options?order_type=fba&country=USGET order_type=ocean/air/express/fba (default ocean). Returns shared goods_types, pcs_units, container_sizes, transport_types, shipping_modes, bill_types, custom_types, insurance_options and payment_options, with label/value pairs. Also air_transport_types/air_modes and fba_types/fba_transports. Express/FBA add active channels (up to 30; keyword filter). FBA adds fba_warehouses (up to 50; country and keyword filters).
Order creation does not resolve port names. Use the port dictionary code or rate response resolved.pol.code / resolved.pod.code for ocean, and airport IATA codes for air. Select carriers/airlines from their dictionaries.
URL query parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| order_type | string | No | Order type: ocean, air, express, fba; default ocean. |
| keyword | string | No | Search channel code/name or FBA warehouse code/address, up to 100 characters; default empty. |
| country | string | No | Two-letter destination country filter for FBA warehouses, e.g. US. No country filter by default; does not filter channels. |
Option response fields (inside data)#
| Field | Type | Availability | Description |
|---|---|---|---|
| goods_types | array<object> | Always | Cargo types for goods_type. Each item has label:string (name) and value:string (submit this value). |
| pcs_units | array<object> | Always | Packaging units for goods_pcs_unit. Each item has label:string (name) and value:string (submit this value). |
| container_sizes | array<object> | Always | Ocean container sizes for packing[].ctt. Each item has label:string (name) and value:string (submit this value). |
| transport_types | array<object> | Always | Ocean transport types for transport_type. Each item has label:string (name) and value:string (submit this value). |
| shipping_modes | array<object> | Always | Ocean shipping terms for shipping_mode. Each item has label:string (name) and value:string (submit this value). |
| bill_types | array<object> | Always | Ocean bill of lading types for blt. Each item has label:string (name) and value:integer (submit this value). |
| custom_types | array<object> | Always | Customs types for custom.custom. Each item has label:string (name) and value:integer (submit this value). |
| insurance_options | array<object> | Always | Insurance selection for insurance.is_buy. Each item has label:string (name) and value:integer (submit this value). |
| payment_options | array<object> | Always | Ocean prepaid/collect terms for payment. Each item has label:string (name) and value:integer (submit this value). |
| express_companies | array<object> | Always | Inbound couriers for collecting[].company. Each item has label:string (name) and value:string (submit this value). |
| air_transport_types | array<object> | Always | Air service types for transport_type. Each item has label:string (name) and value:string (submit this value). |
| air_modes | array<object> | Always | Air service terms for air_mode. Each item has label:string (name) and value:integer (submit this value). |
| fba_types | array<object> | Always | FBA/dedicated-line types for fba_type. Each item has label:string (name) and value:integer (submit this value). |
| fba_transports | array<object> | Always | FBA transport modes for transport. Each item has label:string (name) and value:integer (submit this value). |
| channels | array<object> | Express / FBA | Active channels, up to 30 items, for channel. Each item has label:string (name) and value:string (submit this value). |
| fba_warehouses | array<object> | FBA | FBA warehouses, up to 50 items, for fba; extra fields are listed below. Each item has label:string (name) and value:string (submit this value). |
Option objects and extra warehouse fields#
| Field | Type | Availability | Description |
|---|---|---|---|
| label | string | Always | Display name, used by every option list above. |
| value | string | integer | Always | Value to submit to a business field; its exact type is specified per list above. Do not submit label. |
| fba_warehouses[].id | integer | string | Always | Warehouse record ID; use value/code for the fba request field. |
| fba_warehouses[].code | string | Always | Warehouse code, equal to value. |
| fba_warehouses[].country | string | Always | Two-letter warehouse country code. |
| fba_warehouses[].address | string | null | Always | Warehouse address. |
| fba_warehouses[].zip | string | null | Always | Warehouse postal code. |
Own Order Details (Free)#
/api/openapi/v1/orders/detailPOST with order_type and order_no. The single order_no parameter accepts a system order number, Awice reference or work number. Alternatively use client_order_no; it takes priority when both are supplied, without fallback. Matches are exact within the current customer and order type; ambiguous matches return 1001. The response includes order details, contacts, cargo and services. Ocean cargo uses packing; other types use goods_list. bills contains only approved receivables billed to the current customer, or [] when none apply.
For detail lookup, order_no accepts system numbers (SEA… / AIR… / EXP… / FBA…), Awice references (EV… for express; FV… for FBA), or work numbers (AW…). Response order_no always contains the system number; hfs_no and work_no return the other references. Tracking, update and cancel still use the system number or client_order_no.
Order call logs in the developer console show redacted summaries with contact, cargo, extra service, bill and tracking details hidden. Inspect the complete response received by your client for details. log_redacted marks the log summary only and is not an API response field.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| order_type | string | Yes | Order type: ocean, air, express, fba. |
| client_order_no | string | Supply order_no or client_order_no | External reference supplied at API creation; highest priority. |
| order_no | string | Supply order_no or client_order_no | Unified lookup number, up to 100 characters: system order number, Awice reference (EV prefix for express, FV for FBA), or work number (AW prefix). Exact matching with surrounding whitespace trimmed. |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001"
}{
"order_type": "express",
"order_no": "EV261105001CN"
}{
"order_type": "ocean",
"order_no": "AW2026111001"
}Legacy hfs_no and work_no parameters remain supported (string, up to 100 characters); hfs_no applies only to express/FBA. Priority is client_order_no → order_no → hfs_no → work_no, with no fallback when the selected value is not found. New integrations only need order_no. All example numbers are fictitious.
Detail structure (also includes unified order fields)#
| Field | Type | Availability | Description |
|---|---|---|---|
| order_id | integer | Always | Platform order ID. |
| order_no | string | Always | System order number, also when the lookup used an Awice reference or work number. |
| order_type | string | Always | Order type: ocean, air, express, fba. |
| client_order_no | string | null | Always | External reference used in this request; null when operating by system order number without an external reference. |
| work_no | string | Always | Work number with an AW prefix; may be empty. Can be passed directly as order_no for detail lookup. |
| hfs_no | string | Express/FBA only; omitted for ocean/air | Awice reference: EV prefix for express, FV for FBA; may be empty. Can be passed directly as order_no for detail lookup. |
| status | integer | Always | Status: 0 pending, 1 pre-advised, 2 confirmed, 4 received, 5 shipped, 6 returned, 7 voided, 8 out of stock, 9 on hold. |
| status_name | string | Always | Current status label as returned by the server. |
| replayed | boolean | Always | True for a recognized repeat create/update/cancel request; false for detail and tracking. |
| order | object | Always | Current order header. Scalar business fields use the names in the relevant creation table; contact fields are IDs. Additional read-only fields are listed below. |
| sender_info | object | null | Always | Shipper details using the contact fields; null when missing or not owned by the current customer. |
| consignee_info | object | null | Always | Consignee details using the contact fields; null when missing or not owned by the current customer. |
| notifier_info | object | null | Always | Notify-party details using the contact fields; null when missing or not owned by the current customer. |
| custom | object | null | Always | Customs service or null; also includes the customs label, declaration number and attachments listed below. |
| insurance | object | null | Always | Insurance service, same fields as the insurance request object; null when absent. |
| collecting | array<object> | Always | Inbound shipment records, same fields as collecting[]; [] when absent. |
| packup | array<object> | Always | Pickup arrangements, or []; includes request fields and readonly trucker information. |
| packing | array<object> | Ocean only | Container details using the ocean packing[] fields; [] when absent. |
| goods_list | array<object> | Air / Express / FBA | Cargo rows using the corresponding creation item fields. Express/FBA goods[] is returned as goods_list[] in detail responses. |
| bills | array<object> | Always | Your approved receivable bills; see Bills for fields. [] when none are visible. |
| files | array<object> | Always | Attachments marked customer-visible for this order. Hidden files are excluded; [] when none. Fields are listed below. |
Order header fields#
The following tables list the business fields in order. Existing fields are returned for the actual order type. Stored numeric values may be numeric strings; parse by their business type. Child objects and lists are at the data level as listed above, not nested in order. Dates/times are returned as stored without an inferred timezone.
Ocean (FCL / LCL)
| Field | Type | Availability | Description |
|---|---|---|---|
| order.goods_type | string | null | Ocean (FCL / LCL) | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| order.goods_pcs | number | string | null | Ocean (FCL / LCL) | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| order.goods_pcs_unit | string | null | Ocean (FCL / LCL) | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| order.goods_weight | number | string | null | Ocean (FCL / LCL) | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| order.goods_cbm | number | string | null | Ocean (FCL / LCL) | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| order.note | string | null | Ocean (FCL / LCL) | Customer instructions; defaults to an empty string, up to 255 characters. |
| order.pol | string | null | Ocean (FCL / LCL) | Origin port internal code, e.g. CNSHA. Use the port dictionary code, not locode. |
| order.pod | string | null | Ocean (FCL / LCL) | Destination port internal code, e.g. USLSA; must differ from pol. |
| order.carrier | string | null | Ocean (FCL / LCL) | Carrier internal code from the carrier dictionary; defaults to an empty string. |
| order.etc | string | null | Ocean (FCL / LCL) | Expected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string. |
| order.mx | number | string | null | Ocean (FCL / LCL) | Trade direction: 1 import, 2 export (default). |
| order.transport_type | string | null | Ocean (FCL / LCL) | Transport type, default fcl; use lcl for LCL. See transport_types[].value for available values. fcl/fob require container details. |
| order.shipping_mode | string | null | Ocean (FCL / LCL) | Shipping terms from shipping_modes[].value, e.g. CY-CY. |
| order.goods_marks | string | null | Ocean (FCL / LCL) | Shipping marks, up to 4000 characters. |
| order.goods | string | null | Ocean (FCL / LCL) | Cargo name/description, up to 4000 characters; this field is text. |
| order.sender | number | string | null | Ocean (FCL / LCL) | Shipper: your contact ID or a complete contact object; see Contacts. |
| order.consignee | number | string | null | Ocean (FCL / LCL) | Consignee: your contact ID or a complete contact object; see Contacts. |
| order.notifier | number | string | null | Ocean (FCL / LCL) | Notify party: your contact ID or a complete contact object; see Contacts. |
| order.blt | number | string | null | Ocean (FCL / LCL) | Bill of lading type from bill_types[].value, 0–3; default 0. |
| order.payment | number | string | null | Ocean (FCL / LCL) | Freight payment terms: 0 prepaid (default), 1 collect. This is not the bill payment status. |
Air
| Field | Type | Availability | Description |
|---|---|---|---|
| order.goods_type | string | null | Air | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| order.goods_pcs | number | string | null | Air | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| order.goods_pcs_unit | string | null | Air | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| order.goods_weight | number | string | null | Air | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| order.goods_cbm | number | string | null | Air | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| order.note | string | null | Air | Customer instructions; defaults to an empty string, up to 255 characters. |
| order.pol | string | null | Air | Origin airport IATA code, e.g. PVG. |
| order.pod | string | null | Air | Destination airport IATA code, e.g. LAX; must differ from pol. |
| order.airline | string | null | Air | Airline internal code or IATA code from the airline dictionary; defaults to an empty string. |
| order.etc | string | null | Air | Expected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string. |
| order.mx | number | string | null | Air | Trade direction: 1 import, 2 export (default). |
| order.transport_type | string | null | Air | Air service: regular (default), consol (consolidation), or chartered. |
| order.air_mode | number | string | null | Air | Service terms: 0 airport-to-airport (default), 1 DDU, 2 DDP, 3 DAP, 4 customs clearance at both ends. |
| order.goods_marks | string | null | Air | Shipping marks; defaults to an empty string, up to 255 characters. |
| order.goods | string | null | Air | Cargo name/description, up to 255 characters; this field is text. |
| order.sender | number | string | null | Air | Shipper: your contact ID or a complete contact object; see Contacts. |
| order.consignee | number | string | null | Air | Consignee: your contact ID or a complete contact object; see Contacts. |
| order.notifier | number | string | null | Air | Notify party: your contact ID or a complete contact object; see Contacts. |
Express
| Field | Type | Availability | Description |
|---|---|---|---|
| order.goods_type | string | null | Express | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| order.goods_pcs | number | string | null | Express | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| order.goods_pcs_unit | string | null | Express | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| order.goods_weight | number | string | null | Express | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| order.goods_cbm | number | string | null | Express | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| order.note | string | null | Express | Customer instructions; defaults to an empty string, up to 255 characters. |
| order.place_country | string | null | Express | Two-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase. |
| order.channel | string | null | Express | Express channel code from channels[].value in orders/options?order_type=express; must be an active express channel. |
| order.consignee | number | string | null | Express | Consignee: your contact ID or a complete contact object; see Contacts. |
| order.notifier | number | string | null | Express | Notify party: your contact ID or a complete contact object; see Contacts. |
| order.goods_cost | number | string | null | Express | Total declared value: sum of calculated goods[].goods_cost. May be omitted; a valid but inconsistent supplied amount is replaced by the calculated amount. No items means 0; maximum 100000000. |
| order.cost_currency | string | null | Express | Declaration currency, default USD, shared by product unit prices, row values and shipment total. |
| order.fare_declare | number | string | null | Express | Declared freight charge, non-negative; default 0, maximum 100000000. |
FBA / Dedicated line
| Field | Type | Availability | Description |
|---|---|---|---|
| order.goods_type | string | null | FBA / Dedicated line | Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters. |
| order.goods_pcs | number | string | null | FBA / Dedicated line | Total shipping package count, 1–100000000, in goods_pcs_unit. For express, this is the number of packages, not the product quantity in goods[]. |
| order.goods_pcs_unit | string | null | FBA / Dedicated line | Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons. |
| order.goods_weight | number | string | null | FBA / Dedicated line | Total gross weight for the shipment in kg, greater than 0 and at most 100000000. Sum all packages first; the API does not multiply this value by quantity. |
| order.goods_cbm | number | string | null | FBA / Dedicated line | Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0. |
| order.note | string | null | FBA / Dedicated line | Customer instructions; defaults to an empty string, up to 255 characters. |
| order.pod | string | null | FBA / Dedicated line | Two-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase. |
| order.channel | string | null | FBA / Dedicated line | FBA/dedicated-line channel code from channels[].value in orders/options?order_type=fba. |
| order.fba_type | number | string | null | FBA / Dedicated line | Shipment type: 0 FBA warehouse (default), 1 dedicated line. |
| order.transport | number | string | null | FBA / Dedicated line | Transport: 0 ocean, 1 air (default), 2 rail, 3 truck. |
| order.fba | string | null | FBA / Dedicated line | FBA warehouse code from fba_warehouses[].value; must match pod. The warehouse consignee is generated automatically. |
| order.shipment_id | string | null | FBA / Dedicated line | Amazon Shipment ID, up to 255 characters. |
| order.amazon_reference_id | string | null | FBA / Dedicated line | Amazon Reference ID, up to 255 characters. |
| order.sender | number | string | null | FBA / Dedicated line | Shipper, optional: your contact ID or a complete contact object; see Contacts. |
| order.consignee | number | string | null | FBA / Dedicated line | Dedicated-line consignee; generated from the warehouse for FBA shipments: your contact ID or a complete contact object; see Contacts. |
| order.pot | string | null | FBA / Dedicated line | Transit location; defaults to an empty string, up to 255 characters. |
| order.goods_cost | number | string | null | FBA / Dedicated line | Shipment value, non-negative; default 0, maximum 100000000. Sum goods[].sku_amount before submitting. |
Additional read-only order fields#
| Field | Type | Availability | Description |
|---|---|---|---|
| order.etd | integer | string | null | When present on this order type | Legacy date field with its original type and value. For express it represents the original warehouse receipt date; for other types it is the original estimated departure date/time. |
| order.eta | string | null | When present on this order type | Estimated arrival date/time as stored; may be empty. |
| order.vessel | string | null | When present on this order type | Vessel field as stored on the order. |
| order.ves_name | string | null | When present on this order type | Vessel name as stored on the order. |
| order.ves_no | string | null | When present on this order type | Voyage number as stored on the order. |
| order.booking_number | string | null | When present on this order type | Booking number entered by operations; may be empty before assignment. |
| order.hbl_no | string | null | When present on this order type | House bill number; may be empty before assignment. |
| order.mbl_no | string | null | When present on this order type | Master bill number; may be empty before assignment. |
| order.serve_no | string | null | When present on this order type | Service-provider reference as stored on the order. |
| order.receipt_time | string | null | Always returned for FBA details only | FBA warehouse receipt time: YYYY-MM-DD HH:mm:ss in Asia/Shanghai (UTC+08:00). null if missing or invalid. Omitted for express. Historical date-only records use 00:00:00, which does not imply an actual midnight arrival. |
| order.transfer_no | string | null | Always returned for express/FBA details | Unified carrier/forwarding number. Multiple numbers are comma-separated; null if not assigned. The original express order.serve_no remains available for compatibility. |
| order.created_at | integer | string | null | When present on this order type | Creation time as stored; may be a Unix timestamp in seconds or historical date/time text. |
| order.updated_at | integer | string | null | When present on this order type | Last update time as stored; may be a Unix timestamp in seconds or historical date/time text. |
| order.pol_name | string | When applicable to the order type or present in the record | Origin port/airport display name; falls back to the code. |
| order.pod_name | string | When applicable to the order type or present in the record | Destination port/airport/country display name; falls back to the code. |
| order.place_name | string | When applicable to the order type or present in the record | Express destination country name; falls back to the country code. |
| order.carrier_name | string | When applicable to the order type or present in the record | Shipping line/airline display name; falls back to the code. |
| order.channel_name | string | When applicable to the order type or present in the record | Express/FBA channel display name; falls back to channel. |
| order.transport_name | string | When applicable to the order type or present in the record | Transport type display name. |
| order.goods_type_name | string | When applicable to the order type or present in the record | Goods type display name, including combined types. |
| order.air_mode_name | string | When applicable to the order type or present in the record | Air delivery terms label; air_mode still contains the numeric code. |
| order.created_time | string | null | When applicable to the order type or present in the record | Creation time: YYYY-MM-DD HH:mm:ss, Asia/Shanghai; null if missing or invalid. |
| order.track_status | integer | string | null | When applicable to the order type or present in the record | Stored tracking status code; may be empty. Use the tracking endpoint for events. |
| order.track_name | string | null | When applicable to the order type or present in the record | Stored tracking status label, when present. |
| order.cost_currency | string | null | When applicable to the order type or present in the record | Declared-value currency, when present on the order. |
Additional detail-only fields (not create/update inputs)#
| Field | Type | Availability | Description |
|---|---|---|---|
| custom.custom_name | string | When the parent object or record exists | Customs service label. |
| custom.custom_num | string | null | When the parent object or record exists | Declaration number; null if missing. |
| custom.custom_file | array<string> | When the parent object or record exists | Customs attachment paths, normalized to an array; [] when none. |
| custom.name | array<string> | When the parent object or record exists | Customs attachment names corresponding to the paths; [] when unavailable. |
| insurance.is_buy_name | string | When the parent object or record exists | Insurance selection label. |
| packup[].trucker | string | null | When the parent object or record exists | Pickup driver information; null if missing. |
| goods_list[].goods_weight | number | string | null | When the parent object or record exists | Readonly express item weight in kg when stored; air uses its existing goods_list field. |
| files[].id | integer | When the parent object or record exists | Customer-visible attachment ID. |
| files[].title | string | null | When the parent object or record exists | Attachment title. |
| files[].path | string | When the parent object or record exists | Original attachment path, retained for compatibility. Use the same record's url to view or download. Relative paths belong to https://fms.5688.cn, not the www website host. |
| files[].url | string | null | When the parent object or record exists | Complete HTTP(S) link for viewing or downloading; no domain concatenation needed. Relative paths use https://fms.5688.cn; existing absolute links are preserved. Null when the path is missing or no link can be generated. Browsers usually preview images; save the image or download its content programmatically. |
| files[].created_at | integer | string | null | When the parent object or record exists | Attachment creation time as Unix seconds or legacy date/time text. |
order.receipt_time (warehouse receipt time) is returned only for FBA as YYYY-MM-DD HH:mm:ss in Asia/Shanghai, or null when not recorded. Express omits this field. Both express and FBA retain order.transfer_no (carrier/forwarding number), typed string | null. The partial example below is for FBA.
{
"order_type": "fba",
"order": {
"receipt_time": "2026-11-05 00:00:00",
"transfer_no": "EXAMPLE_CARRIER_NUMBER"
}
}In ocean details, order.booking_number is the booking reference entered by operations; order.mbl_no / order.hbl_no are the master/house bill-of-lading references. These may be empty strings before entry. Order acceptance or approved/paid bills do not guarantee that a booking reference has been assigned.
Ocean payment mode and payment terms#
Ocean payment=0 means prepaid and payment=1 means collect; the default is 0, returned as order.payment in details. This mode does not define a deposit percentage, due date, credit period or credit limit. Confirm those terms with your account representative. Read bills[].pay_status for bill payment status; payment is not a paid/unpaid flag.
Order receivable bills#
Uses the website order-detail rules: the order must belong to the current customer, and the bill payer must also be that customer. Only approved/written-off receivable bills are returned. Pending/reversed bills, payables, other customers’ bills, and split parent/intermediate bills are excluded. A split child uses its own split amount. Parent quote details are shown only for an approved receivable parent of the same order and payer, with matching amounts; otherwise quotes is empty. Totals are grouped by original currency. total_cny is a reference CNY conversion using the website exchange-rate rules: FBA uses receipt date, other order types use ETD. Internal notes, preparers, suppliers, and parent bill identifiers are excluded.
For confirmed charges, read bills[].total_by_currency and quote details. These are current approved receivables, grouped by currency; total_cny is a reference conversion, not actual receipts. Bills can change during processing. The API has no permanently locked final_price, and bills=[] does not mean the shipment is free.
| Field | Type | Availability | Description |
|---|---|---|---|
| bills[].bill_code | string | Always | Bill number for the current customer. |
| bills[].pay_status | integer | Always | Payment status: 0 unpaid, 1 paid. |
| bills[].pay_status_name | string | Always | Payment status label. |
| bills[].total_by_currency | object | Always | Totals by currency, e.g. {"USD":100,"CNY":300}; {} when empty. |
| bills[].total_by_currency.{currency} | number | When the currency is present | Dynamic currency-code key with the amount in that currency. Do not directly add amounts in different currencies. |
| bills[].total_cny | number | Always | CNY reference amount converted using website exchange-rate rules; not the actual received amount. |
| bills[].total_display | string | Always | Display text for original-currency totals. |
| bills[].quotes | array<object> | Always | Charge lines; [] for split bills whose ownership or amount conditions are not met. |
| bills[].quotes[].item | string | Always | Charge code. |
| bills[].quotes[].item_name | string | Always | Charge name. |
| bills[].quotes[].price | number | Always | Unit price in money_type. |
| bills[].quotes[].num | number | Always | Chargeable quantity. |
| bills[].quotes[].unit | string | Always | Billing unit, e.g. shipment or carton. |
| bills[].quotes[].amount | number | Always | Line amount in its original currency. |
| bills[].quotes[].money_type | string | Always | Line currency; returns CNY when absent from the stored record. |
| bills[].quotes[].amount_cny | number | Always | CNY reference amount for this line. |
Detail response example (fictional data)#
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false,
"order": {
"goods_type": "YOUR_GOODS_TYPE",
"goods_pcs": 2,
"goods_pcs_unit": "CTN",
"goods_weight": 20,
"goods_cbm": 0.5,
"pol": "CNSHA",
"pol_name": "Shanghai",
"pod": "USLSA",
"pod_name": "Los Angeles",
"transport_type": "fcl",
"transport_name": "整柜",
"goods_type_name": "普货",
"created_time": "2026-11-05 09:00:00",
"booking_number": "",
"mbl_no": "",
"hbl_no": "",
"blt": 0,
"payment": 0
},
"sender_info": {
"company": "Example Shipper",
"contact": "Sender",
"tel": "+86-00000000000",
"email": "",
"address": "Example origin address",
"post": "",
"duty": ""
},
"consignee_info": {
"company": "Example Consignee",
"contact": "Recipient",
"tel": "+1-555-0100",
"email": "",
"address": "Example destination address",
"post": "",
"duty": ""
},
"notifier_info": null,
"custom": null,
"insurance": null,
"collecting": [],
"packup": [],
"files": [
{
"id": 123,
"title": "example-document.pdf",
"path": "/storage/oms/files/example-document.pdf",
"url": "https://fms.5688.cn/storage/oms/files/example-document.pdf",
"created_at": 1793840400
}
],
"packing": [
{
"ctn_no": "",
"ctt": "20GP",
"seal_no": "",
"ctn_num": 1,
"qty": 2,
"qty_unit": "CTN",
"wgt": 20,
"vol": 0.5
}
],
"bills": [
{
"bill_code": "EXAMPLE_BILL_CODE",
"pay_status": 0,
"pay_status_name": "Unpaid",
"total_by_currency": {
"CNY": 300
},
"total_cny": 300,
"total_display": "CNY 300.00",
"quotes": [
{
"item": "DOC",
"item_name": "Document fee",
"price": 300,
"num": 1,
"unit": "shipment",
"amount": 300,
"money_type": "CNY",
"amount_cny": 300
}
]
}
]
},
"credit_used": 0
}Own-order tracking#
/api/openapi/v1/orders/trackingFixed at 0 credits. Lookup parameters: order_type is ocean/air/express/fba; provide client_order_no or order_no, with client_order_no taking precedence. order_no is the system order number, not a work number or carrier tracking number. Signing, an active verified customer and existing rate limits still apply. Returns saved system and manual events for your own order; it does not query carriers live or initiate collection. Coverage is not guaranteed for every mode or tracking number. events=[] means no saved events and does not prove an invalid number or an unshipped order. Events are sorted newest first; forecasts may appear first and must not be interpreted as completed arrivals or deliveries. Times retain their recorded values without an inferred time zone.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| order_type | string | Yes | Order type: ocean, air, express, fba. |
| client_order_no | string | Supply this or order_no | External order reference supplied at creation; takes priority when order_no is also supplied. |
| order_no | string | Supply this or client_order_no | System order number from data.order_no; do not use the work number, Awice reference or carrier tracking number. |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001"
}Response fields (inside data)#
In addition to events below, data contains all unified order response fields.
| Field | Type | Availability | Description |
|---|---|---|---|
| events | array<object> | Always | Saved events; an empty array when none are available |
| events[].time | string | Always | Event time as recorded |
| events[].place | string | Always | Location; may be empty |
| events[].description | string | Always | Description in the language of the saved record |
| events[].tracking_no | string | Always | Associated tracking number; manual or legacy events may have none |
| events[].is_forecast | boolean | Always | true indicates a forecast, not a completed event |
| events[].has_time | boolean | Always | Whether meaningful time-of-day is available; otherwise show the date |
{
"code": 0,
"msg": "success",
"request_id": "req_example",
"data": {
"order_id": 123,
"order_no": "EXAMPLE_ORDER_NUMBER",
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"work_no": "AW2026111001",
"status": 0,
"status_name": "待确认",
"replayed": false,
"events": [
{
"time": "2026-01-02 10:30:00",
"place": "EXAMPLE_PORT",
"description": "Loaded on vessel",
"tracking_no": "EXAMPLE_TRACKING_NUMBER",
"is_forecast": false,
"has_time": true
}
]
},
"credit_used": 0
}Update your own order (free)#
/api/openapi/v1/orders/updateRequire order_type and either client_order_no or order_no; client_order_no takes precedence when both are supplied. Only your own pending (status=0) or forecast (status=1) orders can be updated; completed orders remain locked. changes must be a non-empty object containing only business fields documented for that order type. Omitted fields and child records retain their current values. Supplied objects/lists replace the entire value; optional child records can be cleared with an empty object/list, but required fields such as FCL packing cannot be cleared. For express orders, supplying goods or goods_cost recalculates line values from quantity × unit price and updates the order value. goods=[] clears the lines and sets the order value to zero; changes to other fields preserve historical values. Contacts follow the same own-contact ID or object rules as creation. Order numbers, customer ownership, internal status, booking numbers, costs, and bills cannot be changed. Returns current order identifiers and status. Repeating an identical update does not create duplicate contacts or update logs and returns replayed=true. Updates retain the original creation deduplication record; retrying the original create request returns the current order.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| order_type | string | Yes | Order type: ocean, air, express, fba. |
| client_order_no | string | Supply this or order_no | External order reference supplied at creation; takes priority when order_no is also supplied. |
| order_no | string | Supply this or client_order_no | System order number from data.order_no; do not use the work number, Awice reference or carrier tracking number. |
| changes | object | Yes | Non-empty changes object using business fields from the matching creation table, excluding client_order_no. Submitted child objects/lists replace existing ones; omitted fields are preserved. |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"changes": {
"goods_weight": 1200,
"note": "Updated shipping instructions"
}
}Response fields (inside data)#
The response data contains all Unified order response fields. replayed identifies a repeat operation; status/status_name reflect the resulting state. Unified order response
Cancel / void your own order (free)#
/api/openapi/v1/orders/cancelRequire order_type and either client_order_no or order_no. reason is optional, up to 200 characters. Only your own pending orders (status=0) can be cancelled online. Cancellation sets status=7 (void) and retains the order and audit history. Forecast, confirmed, received, shipped, and other states require your account representative. Repeating cancellation of an already void order returns its current result with replayed=true and does not create duplicate cancellation logs. This follows the website void workflow; it does not issue refunds or cancel a booking with a carrier.
Request parameters#
| Field | Type | Required | Description |
|---|---|---|---|
| order_type | string | Yes | Order type: ocean, air, express, fba. |
| client_order_no | string | Supply this or order_no | External order reference supplied at creation; takes priority when order_no is also supplied. |
| order_no | string | Supply this or client_order_no | System order number from data.order_no; do not use the work number, Awice reference or carrier tracking number. |
| reason | string | No | Cancellation reason, up to 200 characters; defaults to an empty string. |
{
"order_type": "ocean",
"client_order_no": "MY-ORDER-001",
"reason": "Shipment no longer needed"
}Response fields (inside data)#
The response data contains all Unified order response fields. replayed identifies a repeat operation; status/status_name reflect the resulting state. Unified order response
Errors#
Missing or invalid creation fields return HTTP400 / code1001. The errors list includes field (exact path), label (Chinese field name) and message. Array indices start at 0, e.g. packing.0.ctn_num. msg summarizes the problems for display. Authentication and identity checks still run first. Failed creation adds no order and charges no credits; correct all returned errors and retry with the same customer reference.
Field validation errors (at response root)#
| Field | Type | Availability | Description |
|---|---|---|---|
| errors | array<object> | On field validation errors | Field validation errors; not included in every error response. |
| errors[].field | string | Always | Exact field path with zero-based indexes, e.g. goods.0.goods_price. |
| errors[].label | string | Always | Chinese field label. |
| errors[].message | string | Always | Explanation of the field error. |
{
"code": 1001,
"msg": "参数校验失败:起运港/机场(pol)不能为空;目的港/机场或国家(pod)不能为空",
"request_id": "req_example",
"errors": [
{
"field": "pol",
"label": "起运港/机场",
"message": "起运港/机场(pol)不能为空"
},
{
"field": "pod",
"label": "目的港/机场或国家",
"message": "目的港/机场或国家(pod)不能为空"
}
],
"credit_used": 0
}1001 / HTTP400: validation failure; creation errors list missing/invalid fields, dictionary or contact problems. 1003 / HTTP409: customer reference conflicts with another payload. 2007 / HTTP403: unavailable/unverified customer; verification at https://www.5688.cn/user/profile. 4001 / HTTP429: rate limit. Failed creation leaves no partial order; missing or foreign details return 1001. 1004 / HTTP409: the order state does not allow updates or online cancellation; contact your account representative.