1688 freight template
POST /v1/products/freight/template
Domestic shipping rules, estimate and package dimensions. Calls the official API directly; does not create an order or guarantee final payable shipping.
com.alibaba.fenxiao.crossborder:product.freight.estimate-1 · 1688
Live API Key with product:detail and existing 1688 authorization. Success costs 2 API Units, including SKU mapping and freight lookup; failures deduct no units. No AI Credits check/charge even with shop or X-Shop-Domain. Sandbox: 422 SANDBOX_CAPABILITY_UNAVAILABLE.
Request
Use skus[].spec_id from standard 1688 detail variants[].sku_id, as in order preview/create. HIOBuy maps it to original skuId internally. Between 1 and 100 unique SKUs, positive safe-integer quantities, safe total. total_quantity is calculated automatically. Unknown specs are rejected before freight lookup.
POST /v1/products/freight/template
{
"channel": "1688",
"product_id": "111111111",
"destination": {
"province": "浙江省",
"city": "杭州市",
"district": "滨江区"
},
"skus": [
{
"spec_id": "b266e0726506185beaf205cbae88530d",
"quantity": 3
}
]
}Destination names and codes
Supply all three Chinese names or all three six-digit codes below. Unambiguous verified short forms are supported; both forms must agree when supplied together. The bundled mainland dataset is dated 2023-06-30, and its source is no longer updated. New areas can use current explicit codes, subject to upstream acceptance. Municipalities are resolved within their province. Towns in Dongguan, Zhongshan, Danzhou and Jiayuguan map to the county-equivalent six-digit city, never a nine-digit street code. Unknown or ambiguous names are rejected. New explicit codes may have null city/district names.
province / city / district → province_code / city_code / district_code
{
"destination": {
"province_code": "330000",
"city_code": "330100",
"district_code": "330108"
}
}Administrative-divisions-of-China
Response
Standard money is CNY fen (CNY_minor): 490 = CNY 4.90. Weight is kg, dimensions cm. dimensions_source=product (official sizeValueType=1) selects product_dimensions; sku (type 2) selects each SKU’s dimensions. Missing/invalid values are null; explicit free postage sets freight to zero. discount is not applied a second time. response_format=upstream preserves the original envelope, fields, skuId and yuan amounts without monetary_unit. Supplier failures return 502 in both formats. Response below is illustrative.
charge_type: weight / quantity / volume → charge_unit: kg / item / m3
template.type: seller_paid / custom / official_custom
template.shipping_method: express / freight / cash_on_delivery / official
{
"request_id": "req_example",
"monetary_unit": "CNY_minor",
"freight_template": {
"channel": "1688",
"product_id": "111111111",
"destination": {
"province": "浙江省",
"province_code": "330000",
"city": "杭州市",
"city_code": "330100",
"district": "滨江区",
"district_code": "330108"
},
"total_quantity": 3,
"free_postage": false,
"freight": {
"amount": 490,
"currency": "CNY"
},
"discount": 1,
"template": {
"id": "123456789",
"name": "普通快递运费模板",
"type": "custom",
"shipping_method": "express",
"charge_type": "weight",
"charge_unit": "kg",
"first_unit": 1,
"first_fee": {
"amount": 290,
"currency": "CNY"
},
"next_unit": 1,
"next_fee": {
"amount": 200,
"currency": "CNY"
}
},
"dimensions_source": "sku",
"product_dimensions": null,
"skus": [
{
"spec_id": "b266e0726506185beaf205cbae88530d",
"quantity": 3,
"dimensions": {
"weight_kg": 0.5,
"length_cm": 20,
"width_cm": 15,
"height_cm": 10
}
}
]
}
}Errors
| HTTP | Code |
|---|---|
| 400 | INVALID_DESTINATION, REGION_NOT_FOUND, REGION_AMBIGUOUS, REGION_CODE_MISMATCH, INVALID_PRODUCT_ID, INVALID_SKUS, INVALID_SPEC_ID, DUPLICATE_SPEC_ID, INVALID_QUANTITY |
| 401 / 403 | Authentication |
| 404 | NOT_FOUND |
| 422 | SANDBOX_CAPABILITY_UNAVAILABLE |
| 429 | Rate limits |
| 502 | CHANNEL_UPSTREAM_ERROR |
POST /v1/products/freight/estimate · POST /v1/orders/preview
Get Support
Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days