Docs Menu

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.

Creation, options, details including your receivable bills, updates and void cancellations cost 0 credits, including with a zero balance. Signed authentication, an active app and verified customer account, and existing rate limits still apply. Own-order tracking is also free.

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.

FieldTypeRequiredDescription
client_order_nostringYesYour order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup.
goods_typestringYesCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
goods_pcsintegerYesTotal 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_unitstringNoPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
goods_weightnumberYesTotal 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_cbmnumberRequired for ocean / FBATotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
customobjectNoCustoms service; optional. See Additional services for its fields.
insuranceobjectNoInsurance service; optional. See Additional services for its fields.
collectingarray<object>NoInbound collection shipments, default [], up to 200 items; see Additional services.
packuparray<object>NoPickup arrangements, default [], up to 200 items; see Additional services.
notestringNoCustomer instructions; defaults to an empty string, up to 255 characters.

Ocean (FCL / LCL)#

POST/api/openapi/v1/orders/ocean/create

Supports FCL and LCL. All public top-level request fields are listed below; packing[] contains container details.

Request parameters#

FieldTypeRequiredDescription
client_order_nostringYesYour order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup.
goods_typestringYesCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
goods_pcsintegerYesTotal 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_unitstringNoPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
goods_weightnumberYesTotal 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_cbmnumberRequired for ocean / FBATotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
customobjectNoCustoms service; optional. See Additional services for its fields.
insuranceobjectNoInsurance service; optional. See Additional services for its fields.
collectingarray<object>NoInbound collection shipments, default [], up to 200 items; see Additional services.
packuparray<object>NoPickup arrangements, default [], up to 200 items; see Additional services.
notestringNoCustomer instructions; defaults to an empty string, up to 255 characters.
polstringYesOrigin port internal code, e.g. CNSHA. Use the port dictionary code, not locode.
podstringYesDestination port internal code, e.g. USLSA; must differ from pol.
carrierstringNoCarrier internal code from the carrier dictionary; defaults to an empty string.
etcstringNoExpected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string.
mxintegerNoTrade direction: 1 import, 2 export (default).
transport_typestringNoTransport type, default fcl; use lcl for LCL. See transport_types[].value for available values. fcl/fob require container details.
shipping_modestringYesShipping terms from shipping_modes[].value, e.g. CY-CY.
goods_marksstringYesShipping marks, up to 4000 characters.
goodsstringYesCargo name/description, up to 4000 characters; this field is text.
senderinteger | objectYesShipper: your contact ID or a complete contact object; see Contacts.
consigneeinteger | objectYesConsignee: your contact ID or a complete contact object; see Contacts.
notifierinteger | objectYesNotify party: your contact ID or a complete contact object; see Contacts.
packingarray<object>Required for fcl / fobContainer details, up to 200 items. Cannot be empty for FCL; optional for LCL. Item fields are listed below.
bltintegerNoBill of lading type from bill_types[].value, 0–3; default 0.
paymentintegerNoFreight 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.

FieldTypeRequiredDescription
packing[].ctn_nostringNoContainer number, up to 255 characters.
packing[].cttstringYesContainer size from container_sizes[].value, e.g. 20GP; each submitted item must use a valid size.
packing[].seal_nostringNoSeal number, up to 255 characters.
packing[].ctn_numnumberRequired for fcl / fobContainer count; a positive integer is required for fcl/fob.
packing[].qtynumberNoCargo quantity for this row, non-negative.
packing[].qty_unitstringNoPackaging unit for this row, e.g. CTN.
packing[].wgtnumberNoTotal cargo weight for this row in kg; top-level goods_weight must still be supplied.
packing[].volnumberNoTotal cargo volume for this row in m³; top-level goods_cbm must still be supplied.

Example Request (Replace Option Values Before Submitting)#

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

POST/api/openapi/v1/orders/air/create

All public top-level request fields are listed below. goods_list[] holds cargo rows; supply shipment totals at the top level.

Request parameters#

FieldTypeRequiredDescription
client_order_nostringYesYour order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup.
goods_typestringYesCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
goods_pcsintegerYesTotal 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_unitstringNoPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
goods_weightnumberYesTotal 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_cbmnumberRequired for ocean / FBATotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
customobjectNoCustoms service; optional. See Additional services for its fields.
insuranceobjectNoInsurance service; optional. See Additional services for its fields.
collectingarray<object>NoInbound collection shipments, default [], up to 200 items; see Additional services.
packuparray<object>NoPickup arrangements, default [], up to 200 items; see Additional services.
notestringNoCustomer instructions; defaults to an empty string, up to 255 characters.
polstringYesOrigin airport IATA code, e.g. PVG.
podstringYesDestination airport IATA code, e.g. LAX; must differ from pol.
airlinestringNoAirline internal code or IATA code from the airline dictionary; defaults to an empty string.
etcstringNoExpected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string.
mxintegerNoTrade direction: 1 import, 2 export (default).
transport_typestringNoAir service: regular (default), consol (consolidation), or chartered.
air_modeintegerNoService terms: 0 airport-to-airport (default), 1 DDU, 2 DDP, 3 DAP, 4 customs clearance at both ends.
goods_marksstringNoShipping marks; defaults to an empty string, up to 255 characters.
goodsstringYesCargo name/description, up to 255 characters; this field is text.
senderinteger | objectYesShipper: your contact ID or a complete contact object; see Contacts.
consigneeinteger | objectYesConsignee: your contact ID or a complete contact object; see Contacts.
notifierinteger | objectYesNotify party: your contact ID or a complete contact object; see Contacts.
goods_listarray<object>NoCargo 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.

FieldTypeRequiredDescription
goods_list[].goodsstringNoCargo name for this row, up to 255 characters.
goods_list[].goods_packingstringNoPackaging unit for this row, e.g. CTN.
goods_list[].goods_pcsnumberNoPackage count for this row, non-negative.
goods_list[].goods_weightnumberNoTotal weight for this row in kg.
goods_list[].goods_lengthnumberNoLength of one package in cm.
goods_list[].goods_widthnumberNoWidth of one package in cm.
goods_list[].goods_heightnumberNoHeight of one package in cm.
goods_list[].goods_cbmnumberNoTotal 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)#

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

POST/api/openapi/v1/orders/express/create

Top-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#

FieldTypeRequiredDescription
client_order_nostringYesYour order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup.
goods_typestringYesCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
goods_pcsintegerYesTotal 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_unitstringNoPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
goods_weightnumberYesTotal 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_cbmnumberRequired for ocean / FBATotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
customobjectNoCustoms service; optional. See Additional services for its fields.
insuranceobjectNoInsurance service; optional. See Additional services for its fields.
collectingarray<object>NoInbound collection shipments, default [], up to 200 items; see Additional services.
packuparray<object>NoPickup arrangements, default [], up to 200 items; see Additional services.
notestringNoCustomer instructions; defaults to an empty string, up to 255 characters.
place_countrystringYesTwo-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase.
channelstringYesExpress channel code from channels[].value in orders/options?order_type=express; must be an active express channel.
consigneeinteger | objectYesConsignee: your contact ID or a complete contact object; see Contacts.
notifierinteger | objectYesNotify party: your contact ID or a complete contact object; see Contacts.
goods_costnumberNoTotal 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_currencystringNoDeclaration currency, default USD, shared by product unit prices, row values and shipment total.
fare_declarenumberNoDeclared freight charge, non-negative; default 0, maximum 100000000.
goodsarray<object>NoDeclared 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.

FieldTypeRequiredDescription
goods[].goods_chsstringNoChinese product name, up to 255 characters.
goods[].goods_enstringNoEnglish product name, up to 255 characters.
goods[].goods_pcsnumberNoProduct quantity for this row, not carton count. For two products in one carton, use 2. Omitted quantity means 0 for value calculation.
goods[].goods_pricenumberNoUnit price per product in the top-level cost_currency; omitted price means 0.
goods[].goods_costnumberNoRow 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_hscodestringNoProduct HS code; submit a string to preserve leading zeros, up to 255 characters.
goods[].goods_usestringNoProduct use, up to 255 characters.
goods[].goods_materialstringNoProduct material, up to 255 characters.
goods[].goods_thumbstringNoProduct image URL, up to 255 characters; this is not a binary or Base64 upload field.

Example Request (Replace Option Values Before Submitting)#

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

POST/api/openapi/v1/orders/fba/create

FBA 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#

FieldTypeRequiredDescription
client_order_nostringYesYour order reference: 1–64 case-sensitive letters, digits or . _ : -. Used for idempotency and lookup.
goods_typestringYesCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
goods_pcsintegerYesTotal 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_unitstringNoPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
goods_weightnumberYesTotal 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_cbmnumberRequired for ocean / FBATotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
customobjectNoCustoms service; optional. See Additional services for its fields.
insuranceobjectNoInsurance service; optional. See Additional services for its fields.
collectingarray<object>NoInbound collection shipments, default [], up to 200 items; see Additional services.
packuparray<object>NoPickup arrangements, default [], up to 200 items; see Additional services.
notestringNoCustomer instructions; defaults to an empty string, up to 255 characters.
podstringYesTwo-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase.
channelstringYesFBA/dedicated-line channel code from channels[].value in orders/options?order_type=fba.
fba_typeintegerNoShipment type: 0 FBA warehouse (default), 1 dedicated line.
transportintegerNoTransport: 0 ocean, 1 air (default), 2 rail, 3 truck.
fbastringRequired if fba_type = 0FBA warehouse code from fba_warehouses[].value; must match pod. The warehouse consignee is generated automatically.
shipment_idstringRequired if fba_type = 0Amazon Shipment ID, up to 255 characters.
amazon_reference_idstringRequired if fba_type = 0Amazon Reference ID, up to 255 characters.
senderinteger | objectNoShipper, optional: your contact ID or a complete contact object; see Contacts.
consigneeinteger | objectRequired if fba_type = 1Dedicated-line consignee; generated from the warehouse for FBA shipments: your contact ID or a complete contact object; see Contacts.
potstringNoTransit location; defaults to an empty string, up to 255 characters.
goods_costnumberNoShipment value, non-negative; default 0, maximum 100000000. Sum goods[].sku_amount before submitting.
goodsarray<object>NoSKU 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.

FieldTypeRequiredDescription
goods[].sku_nostringNoSKU reference, up to 255 characters.
goods[].sku_packingstringNoPackaging unit, e.g. CTN.
goods[].sku_box_numberstringNoCarton number or range, up to 255 characters.
goods[].sku_nwnumberNoNet weight per carton in kg.
goods[].sku_gwnumberNoGross weight per carton in kg; row gross weight = sku_ctns × sku_gw.
goods[].sku_lengthnumberNoCarton length in cm.
goods[].sku_widthnumberNoCarton width in cm.
goods[].sku_heightnumberNoCarton height in cm.
goods[].sku_ctnsnumberNoCarton count for this SKU, non-negative.
goods[].sku_pcsnumberNoTotal product quantity for this SKU, not quantity per carton; used with unit price to calculate row value.
goods[].sku_pricenumberNoProduct unit price; the website uses USD.
goods[].sku_amountnumberNoRow value; calculate sku_pcs × sku_price before submitting. The website uses USD.
goods[].sku_volnumberNoTotal row volume in m³; calculate sku_ctns × length × width × height ÷ 1000000 before submitting.
goods[].sku_weightnumberNoTotal gross weight for this row in kg; calculate sku_ctns × sku_gw before submitting.

Example Request (Replace Option Values Before Submitting)#

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

FieldTypeRequiredDescription
companystringYesCompany/organization name, up to 255 characters.
contactstringYesContact person, up to 255 characters.
telstringYesTelephone number, preferably with international dialing code; up to 255 characters.
addressstringYesFull address including state/province, city and street, up to 4000 characters. No separate province/city fields are accepted.
emailstringNoEmail address, up to 255 characters.
poststringNoPostal code; submit a string to preserve leading zeros, up to 255 characters.
dutystringNoTax ID, up to 255 characters.
JSON
{
  "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#

FieldTypeRequiredDescription
custom.custominteger | stringNoCustoms 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#

FieldTypeRequiredDescription
insurance.is_buyintegerNoPurchase insurance: 0 no, 1 yes.
insurance.money_typestringNoInsurance currency, e.g. USD/CNY.
insurance.amountnumberNoInsured amount, non-negative, maximum 100000000.
insurance.beneficiarystringNoBeneficiary, up to 100 characters.

collecting[] inbound shipments#

FieldTypeRequiredDescription
collecting[].companystringNoInbound courier company from express_companies[].value, up to 255 characters.
collecting[].numberstringNoInbound tracking number, up to 255 characters. Normalized duplicates are rejected. Only your own or unassigned, unlinked warehouse records can be linked.
collecting[].notestringNoInstructions for this inbound shipment, up to 255 characters.

packup[] pickup arrangements#

FieldTypeRequiredDescription
packup[].timestringNoRequested pickup time; use YYYY-MM-DD HH:mm:ss, up to 255 characters.
packup[].addressstringNoFull pickup address, up to 4000 characters.
packup[].contactstringNoPickup contact, up to 255 characters.
packup[].telstringNoPickup 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#

FieldTypeAvailabilityDescription
codeintegerAlwaysBusiness code: 0 for success; see error documentation for other values.
msgstringAlwaysResult or error message.
request_idstringAlwaysRequest trace ID; retain it for support.
dataobjectOn successBusiness result. Unless stated otherwise, the response field tables below are relative to data.
credit_usedintegerAfter quota processingCredits used, 0 for order APIs. May be absent on early failures such as authentication errors.
credit_balanceintegerAfter quota processingRemaining credits; -1 means unlimited.
quotaobjectAfter quota processingCredit information corresponding to credit_used and credit_balance.
quota.costintegerWhen quota is presentCredits used by this request, 0 for order APIs.
quota.remainintegerWhen quota is presentRemaining credits; -1 means unlimited.

Response fields (inside data)#

FieldTypeAvailabilityDescription
order_idintegerAlwaysPlatform order ID.
order_nostringAlwaysSystem order number, also when the lookup used an Awice reference or work number.
order_typestringAlwaysOrder type: ocean, air, express, fba.
client_order_nostring | nullAlwaysExternal reference used in this request; null when operating by system order number without an external reference.
work_nostringAlwaysWork number with an AW prefix; may be empty. Can be passed directly as order_no for detail lookup.
hfs_nostringExpress/FBA only; omitted for ocean/airAwice reference: EV prefix for express, FV for FBA; may be empty. Can be passed directly as order_no for detail lookup.
statusintegerAlwaysStatus: 0 pending, 1 pre-advised, 2 confirmed, 4 received, 5 shipped, 6 returned, 7 voided, 8 out of stock, 9 on hold.
status_namestringAlwaysCurrent status label as returned by the server.
replayedbooleanAlwaysTrue for a recognized repeat create/update/cancel request; false for detail and tracking.
JSON
{
  "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)#

GET/api/openapi/v1/orders/options?order_type=fba&country=US

GET 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#

FieldTypeRequiredDescription
order_typestringNoOrder type: ocean, air, express, fba; default ocean.
keywordstringNoSearch channel code/name or FBA warehouse code/address, up to 100 characters; default empty.
countrystringNoTwo-letter destination country filter for FBA warehouses, e.g. US. No country filter by default; does not filter channels.

Option response fields (inside data)#

FieldTypeAvailabilityDescription
goods_typesarray<object>AlwaysCargo types for goods_type. Each item has label:string (name) and value:string (submit this value).
pcs_unitsarray<object>AlwaysPackaging units for goods_pcs_unit. Each item has label:string (name) and value:string (submit this value).
container_sizesarray<object>AlwaysOcean container sizes for packing[].ctt. Each item has label:string (name) and value:string (submit this value).
transport_typesarray<object>AlwaysOcean transport types for transport_type. Each item has label:string (name) and value:string (submit this value).
shipping_modesarray<object>AlwaysOcean shipping terms for shipping_mode. Each item has label:string (name) and value:string (submit this value).
bill_typesarray<object>AlwaysOcean bill of lading types for blt. Each item has label:string (name) and value:integer (submit this value).
custom_typesarray<object>AlwaysCustoms types for custom.custom. Each item has label:string (name) and value:integer (submit this value).
insurance_optionsarray<object>AlwaysInsurance selection for insurance.is_buy. Each item has label:string (name) and value:integer (submit this value).
payment_optionsarray<object>AlwaysOcean prepaid/collect terms for payment. Each item has label:string (name) and value:integer (submit this value).
express_companiesarray<object>AlwaysInbound couriers for collecting[].company. Each item has label:string (name) and value:string (submit this value).
air_transport_typesarray<object>AlwaysAir service types for transport_type. Each item has label:string (name) and value:string (submit this value).
air_modesarray<object>AlwaysAir service terms for air_mode. Each item has label:string (name) and value:integer (submit this value).
fba_typesarray<object>AlwaysFBA/dedicated-line types for fba_type. Each item has label:string (name) and value:integer (submit this value).
fba_transportsarray<object>AlwaysFBA transport modes for transport. Each item has label:string (name) and value:integer (submit this value).
channelsarray<object>Express / FBAActive channels, up to 30 items, for channel. Each item has label:string (name) and value:string (submit this value).
fba_warehousesarray<object>FBAFBA 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#

FieldTypeAvailabilityDescription
labelstringAlwaysDisplay name, used by every option list above.
valuestring | integerAlwaysValue to submit to a business field; its exact type is specified per list above. Do not submit label.
fba_warehouses[].idinteger | stringAlwaysWarehouse record ID; use value/code for the fba request field.
fba_warehouses[].codestringAlwaysWarehouse code, equal to value.
fba_warehouses[].countrystringAlwaysTwo-letter warehouse country code.
fba_warehouses[].addressstring | nullAlwaysWarehouse address.
fba_warehouses[].zipstring | nullAlwaysWarehouse postal code.

Own Order Details (Free)#

POST/api/openapi/v1/orders/detail

POST 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#

FieldTypeRequiredDescription
order_typestringYesOrder type: ocean, air, express, fba.
client_order_nostringSupply order_no or client_order_noExternal reference supplied at API creation; highest priority.
order_nostringSupply order_no or client_order_noUnified 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.
JSON
{
  "order_type": "ocean",
  "client_order_no": "MY-ORDER-001"
}
JSON
{
  "order_type": "express",
  "order_no": "EV261105001CN"
}
JSON
{
  "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)#

FieldTypeAvailabilityDescription
order_idintegerAlwaysPlatform order ID.
order_nostringAlwaysSystem order number, also when the lookup used an Awice reference or work number.
order_typestringAlwaysOrder type: ocean, air, express, fba.
client_order_nostring | nullAlwaysExternal reference used in this request; null when operating by system order number without an external reference.
work_nostringAlwaysWork number with an AW prefix; may be empty. Can be passed directly as order_no for detail lookup.
hfs_nostringExpress/FBA only; omitted for ocean/airAwice reference: EV prefix for express, FV for FBA; may be empty. Can be passed directly as order_no for detail lookup.
statusintegerAlwaysStatus: 0 pending, 1 pre-advised, 2 confirmed, 4 received, 5 shipped, 6 returned, 7 voided, 8 out of stock, 9 on hold.
status_namestringAlwaysCurrent status label as returned by the server.
replayedbooleanAlwaysTrue for a recognized repeat create/update/cancel request; false for detail and tracking.
orderobjectAlwaysCurrent 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_infoobject | nullAlwaysShipper details using the contact fields; null when missing or not owned by the current customer.
consignee_infoobject | nullAlwaysConsignee details using the contact fields; null when missing or not owned by the current customer.
notifier_infoobject | nullAlwaysNotify-party details using the contact fields; null when missing or not owned by the current customer.
customobject | nullAlwaysCustoms service or null; also includes the customs label, declaration number and attachments listed below.
insuranceobject | nullAlwaysInsurance service, same fields as the insurance request object; null when absent.
collectingarray<object>AlwaysInbound shipment records, same fields as collecting[]; [] when absent.
packuparray<object>AlwaysPickup arrangements, or []; includes request fields and readonly trucker information.
packingarray<object>Ocean onlyContainer details using the ocean packing[] fields; [] when absent.
goods_listarray<object>Air / Express / FBACargo rows using the corresponding creation item fields. Express/FBA goods[] is returned as goods_list[] in detail responses.
billsarray<object>AlwaysYour approved receivable bills; see Bills for fields. [] when none are visible.
filesarray<object>AlwaysAttachments 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)

FieldTypeAvailabilityDescription
order.goods_typestring | nullOcean (FCL / LCL)Cargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
order.goods_pcsnumber | string | nullOcean (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_unitstring | nullOcean (FCL / LCL)Packaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
order.goods_weightnumber | string | nullOcean (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_cbmnumber | string | nullOcean (FCL / LCL)Total shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
order.notestring | nullOcean (FCL / LCL)Customer instructions; defaults to an empty string, up to 255 characters.
order.polstring | nullOcean (FCL / LCL)Origin port internal code, e.g. CNSHA. Use the port dictionary code, not locode.
order.podstring | nullOcean (FCL / LCL)Destination port internal code, e.g. USLSA; must differ from pol.
order.carrierstring | nullOcean (FCL / LCL)Carrier internal code from the carrier dictionary; defaults to an empty string.
order.etcstring | nullOcean (FCL / LCL)Expected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string.
order.mxnumber | string | nullOcean (FCL / LCL)Trade direction: 1 import, 2 export (default).
order.transport_typestring | nullOcean (FCL / LCL)Transport type, default fcl; use lcl for LCL. See transport_types[].value for available values. fcl/fob require container details.
order.shipping_modestring | nullOcean (FCL / LCL)Shipping terms from shipping_modes[].value, e.g. CY-CY.
order.goods_marksstring | nullOcean (FCL / LCL)Shipping marks, up to 4000 characters.
order.goodsstring | nullOcean (FCL / LCL)Cargo name/description, up to 4000 characters; this field is text.
order.sendernumber | string | nullOcean (FCL / LCL)Shipper: your contact ID or a complete contact object; see Contacts.
order.consigneenumber | string | nullOcean (FCL / LCL)Consignee: your contact ID or a complete contact object; see Contacts.
order.notifiernumber | string | nullOcean (FCL / LCL)Notify party: your contact ID or a complete contact object; see Contacts.
order.bltnumber | string | nullOcean (FCL / LCL)Bill of lading type from bill_types[].value, 0–3; default 0.
order.paymentnumber | string | nullOcean (FCL / LCL)Freight payment terms: 0 prepaid (default), 1 collect. This is not the bill payment status.

Air

FieldTypeAvailabilityDescription
order.goods_typestring | nullAirCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
order.goods_pcsnumber | string | nullAirTotal 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_unitstring | nullAirPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
order.goods_weightnumber | string | nullAirTotal 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_cbmnumber | string | nullAirTotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
order.notestring | nullAirCustomer instructions; defaults to an empty string, up to 255 characters.
order.polstring | nullAirOrigin airport IATA code, e.g. PVG.
order.podstring | nullAirDestination airport IATA code, e.g. LAX; must differ from pol.
order.airlinestring | nullAirAirline internal code or IATA code from the airline dictionary; defaults to an empty string.
order.etcstring | nullAirExpected cargo-ready date; use YYYY-MM-DD. Defaults to an empty string.
order.mxnumber | string | nullAirTrade direction: 1 import, 2 export (default).
order.transport_typestring | nullAirAir service: regular (default), consol (consolidation), or chartered.
order.air_modenumber | string | nullAirService terms: 0 airport-to-airport (default), 1 DDU, 2 DDP, 3 DAP, 4 customs clearance at both ends.
order.goods_marksstring | nullAirShipping marks; defaults to an empty string, up to 255 characters.
order.goodsstring | nullAirCargo name/description, up to 255 characters; this field is text.
order.sendernumber | string | nullAirShipper: your contact ID or a complete contact object; see Contacts.
order.consigneenumber | string | nullAirConsignee: your contact ID or a complete contact object; see Contacts.
order.notifiernumber | string | nullAirNotify party: your contact ID or a complete contact object; see Contacts.

Express

FieldTypeAvailabilityDescription
order.goods_typestring | nullExpressCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
order.goods_pcsnumber | string | nullExpressTotal 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_unitstring | nullExpressPackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
order.goods_weightnumber | string | nullExpressTotal 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_cbmnumber | string | nullExpressTotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
order.notestring | nullExpressCustomer instructions; defaults to an empty string, up to 255 characters.
order.place_countrystring | nullExpressTwo-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase.
order.channelstring | nullExpressExpress channel code from channels[].value in orders/options?order_type=express; must be an active express channel.
order.consigneenumber | string | nullExpressConsignee: your contact ID or a complete contact object; see Contacts.
order.notifiernumber | string | nullExpressNotify party: your contact ID or a complete contact object; see Contacts.
order.goods_costnumber | string | nullExpressTotal 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_currencystring | nullExpressDeclaration currency, default USD, shared by product unit prices, row values and shipment total.
order.fare_declarenumber | string | nullExpressDeclared freight charge, non-negative; default 0, maximum 100000000.

FBA / Dedicated line

FieldTypeAvailabilityDescription
order.goods_typestring | nullFBA / Dedicated lineCargo type from goods_types[].value in booking options; comma-separate multiple values, up to 50 characters.
order.goods_pcsnumber | string | nullFBA / Dedicated lineTotal 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_unitstring | nullFBA / Dedicated linePackaging unit; defaults to CTN. Use pcs_units[].value; CTN means cartons.
order.goods_weightnumber | string | nullFBA / Dedicated lineTotal 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_cbmnumber | string | nullFBA / Dedicated lineTotal shipment volume in m³, at most 100000000. Must be positive for ocean/FBA; optional for air/express, default 0.
order.notestring | nullFBA / Dedicated lineCustomer instructions; defaults to an empty string, up to 255 characters.
order.podstring | nullFBA / Dedicated lineTwo-letter destination country code, e.g. US; must exist in the country dictionary. Converted to uppercase.
order.channelstring | nullFBA / Dedicated lineFBA/dedicated-line channel code from channels[].value in orders/options?order_type=fba.
order.fba_typenumber | string | nullFBA / Dedicated lineShipment type: 0 FBA warehouse (default), 1 dedicated line.
order.transportnumber | string | nullFBA / Dedicated lineTransport: 0 ocean, 1 air (default), 2 rail, 3 truck.
order.fbastring | nullFBA / Dedicated lineFBA warehouse code from fba_warehouses[].value; must match pod. The warehouse consignee is generated automatically.
order.shipment_idstring | nullFBA / Dedicated lineAmazon Shipment ID, up to 255 characters.
order.amazon_reference_idstring | nullFBA / Dedicated lineAmazon Reference ID, up to 255 characters.
order.sendernumber | string | nullFBA / Dedicated lineShipper, optional: your contact ID or a complete contact object; see Contacts.
order.consigneenumber | string | nullFBA / Dedicated lineDedicated-line consignee; generated from the warehouse for FBA shipments: your contact ID or a complete contact object; see Contacts.
order.potstring | nullFBA / Dedicated lineTransit location; defaults to an empty string, up to 255 characters.
order.goods_costnumber | string | nullFBA / Dedicated lineShipment value, non-negative; default 0, maximum 100000000. Sum goods[].sku_amount before submitting.

Additional read-only order fields#

FieldTypeAvailabilityDescription
order.etdinteger | string | nullWhen present on this order typeLegacy 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.etastring | nullWhen present on this order typeEstimated arrival date/time as stored; may be empty.
order.vesselstring | nullWhen present on this order typeVessel field as stored on the order.
order.ves_namestring | nullWhen present on this order typeVessel name as stored on the order.
order.ves_nostring | nullWhen present on this order typeVoyage number as stored on the order.
order.booking_numberstring | nullWhen present on this order typeBooking number entered by operations; may be empty before assignment.
order.hbl_nostring | nullWhen present on this order typeHouse bill number; may be empty before assignment.
order.mbl_nostring | nullWhen present on this order typeMaster bill number; may be empty before assignment.
order.serve_nostring | nullWhen present on this order typeService-provider reference as stored on the order.
order.receipt_timestring | nullAlways returned for FBA details onlyFBA 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_nostring | nullAlways returned for express/FBA detailsUnified carrier/forwarding number. Multiple numbers are comma-separated; null if not assigned. The original express order.serve_no remains available for compatibility.
order.created_atinteger | string | nullWhen present on this order typeCreation time as stored; may be a Unix timestamp in seconds or historical date/time text.
order.updated_atinteger | string | nullWhen present on this order typeLast update time as stored; may be a Unix timestamp in seconds or historical date/time text.
order.pol_namestringWhen applicable to the order type or present in the recordOrigin port/airport display name; falls back to the code.
order.pod_namestringWhen applicable to the order type or present in the recordDestination port/airport/country display name; falls back to the code.
order.place_namestringWhen applicable to the order type or present in the recordExpress destination country name; falls back to the country code.
order.carrier_namestringWhen applicable to the order type or present in the recordShipping line/airline display name; falls back to the code.
order.channel_namestringWhen applicable to the order type or present in the recordExpress/FBA channel display name; falls back to channel.
order.transport_namestringWhen applicable to the order type or present in the recordTransport type display name.
order.goods_type_namestringWhen applicable to the order type or present in the recordGoods type display name, including combined types.
order.air_mode_namestringWhen applicable to the order type or present in the recordAir delivery terms label; air_mode still contains the numeric code.
order.created_timestring | nullWhen applicable to the order type or present in the recordCreation time: YYYY-MM-DD HH:mm:ss, Asia/Shanghai; null if missing or invalid.
order.track_statusinteger | string | nullWhen applicable to the order type or present in the recordStored tracking status code; may be empty. Use the tracking endpoint for events.
order.track_namestring | nullWhen applicable to the order type or present in the recordStored tracking status label, when present.
order.cost_currencystring | nullWhen applicable to the order type or present in the recordDeclared-value currency, when present on the order.

Additional detail-only fields (not create/update inputs)#

FieldTypeAvailabilityDescription
custom.custom_namestringWhen the parent object or record existsCustoms service label.
custom.custom_numstring | nullWhen the parent object or record existsDeclaration number; null if missing.
custom.custom_filearray<string>When the parent object or record existsCustoms attachment paths, normalized to an array; [] when none.
custom.namearray<string>When the parent object or record existsCustoms attachment names corresponding to the paths; [] when unavailable.
insurance.is_buy_namestringWhen the parent object or record existsInsurance selection label.
packup[].truckerstring | nullWhen the parent object or record existsPickup driver information; null if missing.
goods_list[].goods_weightnumber | string | nullWhen the parent object or record existsReadonly express item weight in kg when stored; air uses its existing goods_list field.
files[].idintegerWhen the parent object or record existsCustomer-visible attachment ID.
files[].titlestring | nullWhen the parent object or record existsAttachment title.
files[].pathstringWhen the parent object or record existsOriginal 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[].urlstring | nullWhen the parent object or record existsComplete 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_atinteger | string | nullWhen the parent object or record existsAttachment 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.

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

FieldTypeAvailabilityDescription
bills[].bill_codestringAlwaysBill number for the current customer.
bills[].pay_statusintegerAlwaysPayment status: 0 unpaid, 1 paid.
bills[].pay_status_namestringAlwaysPayment status label.
bills[].total_by_currencyobjectAlwaysTotals by currency, e.g. {"USD":100,"CNY":300}; {} when empty.
bills[].total_by_currency.{currency}numberWhen the currency is presentDynamic currency-code key with the amount in that currency. Do not directly add amounts in different currencies.
bills[].total_cnynumberAlwaysCNY reference amount converted using website exchange-rate rules; not the actual received amount.
bills[].total_displaystringAlwaysDisplay text for original-currency totals.
bills[].quotesarray<object>AlwaysCharge lines; [] for split bills whose ownership or amount conditions are not met.
bills[].quotes[].itemstringAlwaysCharge code.
bills[].quotes[].item_namestringAlwaysCharge name.
bills[].quotes[].pricenumberAlwaysUnit price in money_type.
bills[].quotes[].numnumberAlwaysChargeable quantity.
bills[].quotes[].unitstringAlwaysBilling unit, e.g. shipment or carton.
bills[].quotes[].amountnumberAlwaysLine amount in its original currency.
bills[].quotes[].money_typestringAlwaysLine currency; returns CNY when absent from the stored record.
bills[].quotes[].amount_cnynumberAlwaysCNY reference amount for this line.

Detail response example (fictional data)#

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

POST/api/openapi/v1/orders/tracking

Fixed 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#

FieldTypeRequiredDescription
order_typestringYesOrder type: ocean, air, express, fba.
client_order_nostringSupply this or order_noExternal order reference supplied at creation; takes priority when order_no is also supplied.
order_nostringSupply this or client_order_noSystem order number from data.order_no; do not use the work number, Awice reference or carrier tracking number.
JSON
{
  "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.

FieldTypeAvailabilityDescription
eventsarray<object>AlwaysSaved events; an empty array when none are available
events[].timestringAlwaysEvent time as recorded
events[].placestringAlwaysLocation; may be empty
events[].descriptionstringAlwaysDescription in the language of the saved record
events[].tracking_nostringAlwaysAssociated tracking number; manual or legacy events may have none
events[].is_forecastbooleanAlwaystrue indicates a forecast, not a completed event
events[].has_timebooleanAlwaysWhether meaningful time-of-day is available; otherwise show the date
JSON
{
  "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)#

POST/api/openapi/v1/orders/update

Require 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#

FieldTypeRequiredDescription
order_typestringYesOrder type: ocean, air, express, fba.
client_order_nostringSupply this or order_noExternal order reference supplied at creation; takes priority when order_no is also supplied.
order_nostringSupply this or client_order_noSystem order number from data.order_no; do not use the work number, Awice reference or carrier tracking number.
changesobjectYesNon-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.
JSON
{
  "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)#

POST/api/openapi/v1/orders/cancel

Require 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#

FieldTypeRequiredDescription
order_typestringYesOrder type: ocean, air, express, fba.
client_order_nostringSupply this or order_noExternal order reference supplied at creation; takes priority when order_no is also supplied.
order_nostringSupply this or client_order_noSystem order number from data.order_no; do not use the work number, Awice reference or carrier tracking number.
reasonstringNoCancellation reason, up to 200 characters; defaults to an empty string.
JSON
{
  "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)#

FieldTypeAvailabilityDescription
errorsarray<object>On field validation errorsField validation errors; not included in every error response.
errors[].fieldstringAlwaysExact field path with zero-based indexes, e.g. goods.0.goods_price.
errors[].labelstringAlwaysChinese field label.
errors[].messagestringAlwaysExplanation of the field error.
JSON
{
  "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.