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

HTTPCode
400INVALID_DESTINATION, REGION_NOT_FOUND, REGION_AMBIGUOUS, REGION_CODE_MISMATCH, INVALID_PRODUCT_ID, INVALID_SKUS, INVALID_SPEC_ID, DUPLICATE_SPEC_ID, INVALID_QUANTITY
401 / 403Authentication
404NOT_FOUND
422SANDBOX_CAPABILITY_UNAVAILABLE
429Rate limits
502CHANNEL_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

Email support