Shipping quotes API

POST /v1/fulfillment/shipping/quotes estimates international shipping from a destination, weight, dimensions, item attributes, and services.

Use the single-package shorthand when the warehouse split is unknown. Use packages[] when the package count and per-package measurements are already known.

This endpoint uses the same channel, region, service, billing, and money terminology as the Shipping channels API.

Quotes are budgets, not locked prices. Warehouse weighing, volume measurement, re-packing, and service review can change the final amount. A COMPLETE quote is still not a price lock.

Compatibility alias: POST /v1/fulfillment/shipments/freight/estimate (same behavior). Prefer /v1/fulfillment/shipping/quotes.

Money and units {#units}

• All money amount values are integer CNY fen. 5000 means ¥50.00.
• Top-level monetary_unit is always CNY_minor.
• Money objects use { "amount": 5000, "currency": "CNY" }.
• Request weight is always KG. Package dimensions are always CM.
• Identify channels and services by stable code, not name.

Request headers {#request}

POST /v1/fulfillment/shipping/quotes
Authorization: Bearer hio_live_xxx
Content-Type: application/json
Language: en

Display language is the Language header only. Supported values: en (default), en-US, zh, zh-CN, zh-TW, cn, hk. Do not put language in the JSON body or query string.

Two request formats {#request-formats}

Do not combine the single-package shorthand fields (weight_kg, length_cm, width_cm, height_cm) with packages[]. The API rejects a mixed request with 400 VALIDATION_ERROR.

Format A — single-package shorthand {#format-a}

Use this when you know the destination and estimated total weight, but not how the warehouse will split boxes.

Minimal request:

{
  "destination": {
    "country_code": "KR"
  },
  "weight_kg": 2.05
}

Single package with dimensions:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "attributes": []
}

• weight_kg is the estimated shipment weight in KG.
• length_cm, width_cm, and height_cm are CM. Provide all three or omit all three.
• Prefer this format when the final warehouse split is unknown. Missing dimensions may produce PARTIAL or REVIEW_REQUIRED for volumetric channels.

Format B — known packages {#format-b}

Use packages[] when you already know the box count and each box’s data.

Single declared package:

{
  "destination": {
    "country_code": "KR"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 2.05,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    }
  ]
}

Multiple packages:

{
  "destination": {
    "country_code": "KR",
    "postal_code": "04524"
  },
  "packages": [
    {
      "reference": "box-1",
      "weight": {
        "value": 1.25,
        "unit": "KG"
      },
      "dimensions": {
        "length": 30,
        "width": 20,
        "height": 10,
        "unit": "CM"
      }
    },
    {
      "reference": "box-2",
      "weight": {
        "value": 0.8,
        "unit": "KG"
      },
      "dimensions": {
        "length": 20,
        "width": 15,
        "height": 8,
        "unit": "CM"
      }
    }
  ]
}

packages[] rules (OpenAPI):

• 1–200 packages.
• One element is an explicit single package. Multiple elements are an explicit multi-package shipment.
• reference is optional, but must be unique within the request.
• packages[].weight is required. packages[].weight.unit must be KG.
• packages[].dimensions is optional. When present, length, width, height, and unit are all required. unit must be CM.

The Gateway maps format A to a single warehouse package. Format B is validated and mapped as declared. Final split and measured dimensions are still determined after warehouse processing.

Shared request fields {#shared-fields}

Both formats may include the following.

destination

declared_value

{
  "amount": 5000,
  "currency": "CNY"
}

Shipment-level declared value in integer CNY fen. Omit the field when unknown. Do not send 0 to mean unknown.

attributes

Array of stable item-attribute codes from GET /v1/fulfillment/shipments/item-attributes. Unique strings, max 100.

Quotes are first limited to channels applicable to destination.country_code; channels for other countries are omitted. Each remaining channel evaluates the declared attributes independently. Unsupported attributes produce UNAVAILABLE with ATTRIBUTE_NOT_SUPPORTED, while other applicable channels may still return quotes.

services

{
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  }
}

Each item requires code and quantity. OpenAPI: quantity is an integer from 1 to 999. Codes must be unique within each group.

channel_codes

Stable channel codes that restrict the quote set. Omit to quote all candidate channels. Do not send an empty array. An unknown or inaccessible code returns 400 INVALID_SHIPPING_CHANNEL for the whole request.

Complete request example {#complete-request}

Format A with destination, dimensions, declared value, attributes, services, and a channel filter:

{
  "destination": {
    "country_code": "US",
    "subdivision_code": "US-CA",
    "region": "California",
    "postal_code": "90001"
  },
  "weight_kg": 2.05,
  "length_cm": 30,
  "width_cm": 20,
  "height_cm": 10,
  "declared_value": {
    "amount": 5000,
    "currency": "CNY"
  },
  "attributes": [
    "GENERAL_CARGO"
  ],
  "services": {
    "channel": [
      {
        "code": "LINE_INSURANCE",
        "quantity": 1
      }
    ],
    "outbound": [
      {
        "code": "VACUUM_PACKING",
        "quantity": 1
      }
    ],
    "inbound": [
      {
        "code": "PHOTO",
        "quantity": 3
      }
    ]
  },
  "channel_codes": [
    "US-SEA"
  ]
}

Response {#response}

{
  "success": true,
  "estimate_type": "DECLARED",
  "completeness": {
    "level": "HIGH",
    "destination": "COMPLETE",
    "package_dimensions": "COMPLETE",
    "package_split": "DECLARED",
    "declared_value": "PROVIDED",
    "attributes": "DECLARED",
    "services": "REQUESTED_ONLY"
  },
  "warnings": [
    {
      "code": "WAREHOUSE_REVIEW_REQUIRED",
      "message": "Final charges require warehouse measurement, packing and service review.",
      "affects": [
        "FINAL_CHARGES"
      ]
    }
  ],
  "quotes": [
    {
      "channel": {
        "code": "US-SEA",
        "name": "US Ocean",
        "description": "General cargo line",
        "tags": [
          "GREAT_VALUE"
        ],
        "capabilities": {
          "delivery_methods": [
            "DOOR_DELIVERY",
            "PICKUP"
          ]
        }
      },
      "available": true,
      "quote_status": "COMPLETE",
      "unavailable_reason": null,
      "attribute_evaluation": {
        "status": "SUPPORTED",
        "declared_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ],
        "unsupported_attributes": []
      },
      "matched_region": {
        "code": "US-WEST",
        "name": "US West",
        "match_type": "COUNTRY_REGION"
      },
      "packages": [
        {
          "reference": "box-1",
          "weight": {
            "value": 2.05,
            "unit": "KG"
          },
          "dimensions": {
            "length": 30,
            "width": 20,
            "height": 10,
            "unit": "CM"
          },
          "weights": {
            "actual": {
              "value": 2.05,
              "unit": "KG"
            },
            "volumetric": {
              "value": 1,
              "unit": "KG"
            },
            "chargeable": {
              "value": 2.5,
              "unit": "KG"
            }
          }
        }
      ],
      "weights": {
        "actual": {
          "value": 2.05,
          "unit": "KG"
        },
        "volumetric": {
          "value": 1,
          "unit": "KG"
        },
        "chargeable": {
          "value": 2.5,
          "unit": "KG"
        }
      },
      "billing_quantity": {
        "value": 2.5,
        "unit": "KG"
      },
      "pricing_selector": {
        "type": "WEIGHT",
        "value": 2.5,
        "unit": "KG",
        "scope": "SHIPMENT"
      },
      "transit_time": {
        "text": "15-18 business days",
        "min_business_days": 15,
        "max_business_days": 18
      },
      "charges": {
        "base_freight": {
          "amount": 10000,
          "currency": "CNY"
        },
        "channel_services": {
          "amount": 550,
          "currency": "CNY",
          "known_amount": 550,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "channel_rules": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": [],
          "aggregation": "SUM_ALL",
          "cap": null
        },
        "outbound_services": {
          "amount": 800,
          "currency": "CNY",
          "known_amount": 800,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "inbound_services": {
          "amount": 300,
          "currency": "CNY",
          "known_amount": 300,
          "calculation_status": "CALCULATED",
          "items": []
        },
        "adjustments": {
          "amount": 0,
          "currency": "CNY",
          "known_amount": 0,
          "calculation_status": "CALCULATED",
          "items": []
        }
      },
      "display_charges": {
        "addition": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        },
        "floor": {
          "amount": 0,
          "currency": "CNY",
          "included_in_total": false
        }
      },
      "total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "known_total": {
        "amount": 11650,
        "currency": "CNY"
      },
      "warnings": [],
      "service_adjustment_possible": true
    }
  ],
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T08:00:00Z",
  "request_id": "req_xxx",
  "disclaimer": "Estimated charges based on declared data."
}

Top-level fields

completeness

Quote status {#quote-status}

Do not decide from available alone. Always read quote_status.

• total is the complete budget when known.
• known_total is the sum of fees that can be calculated now.
• When total is null, do not treat known_total as a complete quote.
• unavailable_reason.code is for programmatic handling.
• unavailable_reason.message is display-only.

UNAVAILABLE on one quote is not an HTTP error.

Quote object {#quotes}

Weights and billing quantity {#weights}

• actual — declared or measured weight.
• volumetric — dimensional weight.
• chargeable — weight used for freight.
• billing_quantity — quantity the channel bills (may be weight, volume, or density).
• pricing_selector — how that quantity selected a rate row. Types match catalog WEIGHT / VOLUME / DENSITY.
• Multi-package channels may round per box and then sum. When pricing_selector.scope is PER_PACKAGE, read each packages[].pricing_selector.

Charges {#charges}

Inbound vs outbound services

Inbound and outbound services represent different stages of warehouse value-added services. Inbound services are performed during warehouse receiving, while outbound services are performed during shipment preparation. Both groups may legitimately appear in the same quote and may both be charged when different services are performed at each stage.

The amounts shown in a shipping quote are estimates of the applicable services only. Requesting a quote does not create or settle a service charge. Final charges are determined by the services actually performed and their final package/shipment service pricing and settlement.

Use both groups when estimating total fulfillment cost, then reconcile each estimated service against its corresponding final actual charge. Do not add a quote estimate again on top of the final charge for the same individual service.

Illustrative quote amounts (all amounts use CNY minor units):

All four estimates may coexist because they are different services performed at different fulfillment stages. Other inbound examples include video recording and receiving-related services requested by the customer; other outbound examples include wooden-frame / wooden-crate packing and outbound handling services.

Each group typically includes:

channel_rules may also include aggregation and cap. Use the group subtotal — do not replace it by summing raw rule items.

aggregation=SUM_ALL accumulates every matched charge. HIGHEST_ONLY sorts by amount and selects only the highest; equal-priced rules are equivalent. cap limits the aggregated subtotal, and null means uncapped.

Charge items

display_charges may exist only for frontend presentation.

PENDING_INPUT, REVIEW_REQUIRED, and other uncalculated rules are excluded from the known total. amount=null is not zero, and a configured charge_value is not an incurred charge.

Unavailable reasons {#unavailable-reasons}

Common unavailable_reason.code values:

OUTSIDE_PRICING_RANGE
POSTAL_CODE_REQUIRED
POSTAL_CODE_NOT_SUPPORTED
DESTINATION_NOT_SUPPORTED
ATTRIBUTE_NOT_SUPPORTED
SERVICE_NOT_SUPPORTED
DIMENSIONS_REQUIRED
DECLARED_VALUE_REQUIRED
MULTI_PACKAGE_NOT_SUPPORTED
PRICING_MODE_UNSUPPORTED
CHANNEL_RULE_REJECTED
CHANNEL_PRICING_ERROR

Unavailable channels stay in quotes[] so you can explain why they were rejected.

Catalog terminology {#catalog-terminology}

Item attributes {#item-attributes}

GET /v1/fulfillment/shipments/item-attributes returns the valid attributes[] codes for quotes.

Errors {#errors}

There is no distinct public AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED, or WAREHOUSE_SERVICE_UNAVAILABLE code. Use 401 INVALID_API_KEY, 403 WAREHOUSE_AUTH_INVALID, and 502 WAREHOUSE_UPSTREAM_ERROR.

A channel that cannot carry this shipment is an UNAVAILABLE quote, not an HTTP failure.

Related {#related}

• Shipping channels — capabilities, coverage, and service codes
• Shipments — create a shipment after parcels are inbound
• Fulfillment overview