Shipping channels API

GET /v1/fulfillment/shipping/channels lists the active, price-configured international shipping channels available through the warehouse connected to your app.

Use this endpoint to build a channel selector or inspect capabilities. For destination-specific availability and amounts, call Shipping quotes. Rate cards here only explain the pricing model — they never lock a price.

GEThttps://open.hiobuy.com/v1/fulfillment/shipping/channels

Requires warehouse fulfillment. A sandbox app with an hio_test_* key receives deterministic mock data.

Quotes are budgets, not locked prices. Warehouse weighing, volume measurement, re-packing, and service review can change the final amount.

Money and units {#units}

All money amount values are integer CNY fen (minor units). 1000 means ¥10.00.
Top-level monetary_unit is always CNY_minor.
Money objects use:

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

KG = kilogram, CM = centimeter, M3 = cubic meter, KG_PER_M3 = kilogram per cubic meter.
Identify channels, regions, and services by stable code, not name.
The Public API does not expose warehouse database IDs, developer codes, or supplier URLs.

Request {#request}

GET /v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards&page=1&page_size=20
Authorization: Bearer hio_live_xxx
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 query string or JSON body.

Query parameters

Parameter	Required	Default	Description
`channel_code`	No	—	Exact stable channel code (max 64 characters)
`country_code`	No	—	ISO 3166-1 alpha-2 destination country
`include`	No	—	Comma-separated expansions: `regions`, `services`, `rate_cards`
`page`	No	`1`	Page number, starting at 1
`page_size`	No	`20`	Items per page; maximum 50

`include` expansions

Omit include for a lightweight channel summary.

`include` value	Response field	Use when
`regions`	`regions`	Coverage, match type, and reference transit time
`services`	`value_added_services`	Channel value-added services for quotes
`rate_cards`	`rate_cards`	Reference price rows that explain the billing model

You may combine values, for example include=regions,services,rate_cards. An unknown value returns 400 VALIDATION_ERROR.

rate_cards are reference_only. They must not replace POST /v1/fulfillment/shipping/quotes. Only include=rate_cards asks the warehouse for price rows.

Only channels that are enabled and have a valid price configuration are returned. An empty items array means no catalog channel matches the current filters.

Response {#response}

{
  "items": [
    {
      "code": "US-SEA",
      "name": "US Ocean",
      "description": "General cargo line",
      "status": "ACTIVE",
      "tags": [
        "GREAT_VALUE"
      ],
      "warehouse": {
        "code": "SZ",
        "name": "Shenzhen Warehouse"
      },
      "capabilities": {
        "delivery_methods": [
          "DOOR_DELIVERY"
        ],
        "multi_package_supported": true,
        "tracking_supported": true,
        "shipping_label_supported": false
      },
      "requirements": {
        "weight": "REQUIRED",
        "dimensions": "CONDITIONAL",
        "postal_code": "OPTIONAL",
        "declared_value": "OPTIONAL",
        "customs_code": "OPTIONAL",
        "personal_customs_code": "OPTIONAL",
        "recipient_identity": "OPTIONAL"
      },
      "attribute_matching": {
        "mode": "ANY_OF",
        "accepted_attributes": [
          {
            "code": "GENERAL",
            "name": "General cargo"
          }
        ]
      },
      "billing": {
        "basis": "WEIGHT",
        "calculation_model": "FIRST_NEXT_WEIGHT",
        "quantity_unit": "KG",
        "supported_range": {
          "minimum": {
            "value": 0.5,
            "unit": "KG"
          },
          "maximum": {
            "value": 30,
            "unit": "KG"
          },
          "out_of_range_behavior": "UNAVAILABLE"
        },
        "minimum": {
          "value": 0.5,
          "unit": "KG",
          "ceil_to_minimum": true
        },
        "rounding": {
          "single_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "multi_package_step": {
            "value": 0.5,
            "unit": "KG"
          },
          "ignore_below": {
            "value": 0.05,
            "unit": "KG"
          }
        },
        "multi_package": {
          "mode": "PER_BOX",
          "calculation_scope": "PER_PACKAGE",
          "aggregation": "SUM_PACKAGE_CHARGES",
          "minimum_per_package": {
            "value": 0.5,
            "unit": "KG"
          },
          "minimum_total": {
            "value": 0,
            "unit": "KG"
          }
        },
        "volumetric_weight": {
          "enabled": true,
          "divisor": 6000,
          "average_with_actual": false,
          "exemption": null
        },
        "overweight_warning": {
          "enabled": false,
          "threshold": {
            "value": 0,
            "unit": "KG"
          },
          "notice": null
        }
      },
      "rule_summary": {
        "fee_aggregation": "SUM_ALL",
        "maximum_charge": {
          "amount": 0,
          "currency": "CNY"
        },
        "has_surcharges": true,
        "has_order_restrictions": false,
        "has_dispatch_restrictions": true,
        "evaluated_by_quote": true
      },
      "regions": [
        {
          "code": "US-WEST",
          "name": "US West",
          "status": "ACTIVE",
          "match_type": "COUNTRY_REGION",
          "countries": [
            "US"
          ],
          "postal_code_required": false,
          "reference_transit_time": {
            "text": "15-18 business days",
            "min_business_days": 15,
            "max_business_days": 18
          },
          "areas": []
        }
      ],
      "value_added_services": [
        {
          "code": "LINE_FUEL",
          "name": "Fuel surcharge",
          "request_mode": "MANDATORY",
          "pricing_type": "CALCULATED",
          "pricing_scope": "REGION",
          "pricing_basis": "BASE_FREIGHT_PERCENT",
          "region_prices": [
            {
              "region_code": "US-WEST",
              "value": 500,
              "value_unit": "BASIS_POINT",
              "fixed_charge": {
                "amount": 200,
                "currency": "CNY"
              }
            }
          ],
          "final_quote_required": true,
          "may_be_adjusted": true
        }
      ],
      "rate_cards": [
        {
          "region_code": "US-WEST",
          "billing_basis": "WEIGHT",
          "calculation_model": "FIRST_NEXT_WEIGHT",
          "quantity_unit": "KG",
          "currency": "CNY",
          "reference_only": true,
          "price_rows": [
            {
              "type": "FIRST_WEIGHT",
              "pricing_basis": "WEIGHT",
              "range": {
                "minimum": 0.5,
                "maximum": 0.5,
                "unit": "KG",
                "minimum_inclusive": true,
                "maximum_inclusive": false
              },
              "first_quantity": {
                "value": 0,
                "unit": "KG"
              },
              "step": {
                "value": 0,
                "unit": "KG"
              },
              "charge": {
                "amount": 8000,
                "currency": "CNY"
              }
            }
          ]
        }
      ],
      "service_policy": {
        "warehouse_may_add_services": true,
        "warehouse_may_remove_services": true,
        "prices_may_change_after_inspection": true
      },
      "final_quote_required": true,
      "config_updated_at": "2026-09-07T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "has_more": false
  },
  "monetary_unit": "CNY_minor",
  "generated_at": "2026-09-07T09:00:00Z",
  "request_id": "req_xxx"
}

regions, value_added_services, and rate_cards appear only when the matching include value is sent.

Response fields {#fields}

Field	Description
`items[]`	Matching channels. Empty when no catalog channel matches the filters.
`items[].code`	Stable channel code. Use this in quotes `channel_codes` and shipment create.
`items[].name`	Localized display name (`Language` header).
`items[].description`	Localized description.
`items[].status`	Catalog status. Returned channels are `ACTIVE`.
`items[].tags`	Stable tags such as `GREAT_VALUE`.
`items[].warehouse`	Bound warehouse `{ code, name }`. Not a database ID.
`items[].capabilities`	Delivery methods, multi-package, tracking, and label support.
`items[].requirements`	Input completeness hints: `REQUIRED` · `OPTIONAL` · `CONDITIONAL` · `NOT_SUPPORTED`.
`items[].attribute_matching`	`ANY_OF` or `ALL_REQUIRED` plus `accepted_attributes[].code`.
`items[].billing`	How the channel prices a shipment. See below.
`items[].rule_summary`	Whether surcharges or restrictions exist; quotes evaluate the rules.
`items[].regions`	Present with `include=regions`.
`items[].value_added_services`	Present with `include=services`.
`items[].rate_cards`	Present with `include=rate_cards`. Always `reference_only`.
`items[].service_policy`	Warehouse may add/remove services and change prices after inspection.
`items[].final_quote_required`	`true` when a shipment-specific quote is still required.
`items[].config_updated_at`	Catalog revision time for this channel.
`pagination`	`page`, `page_size`, `total`, `has_more`.
`monetary_unit`	Always `CNY_minor`.
`generated_at`	Response timestamp (ISO 8601).
`request_id`	Correlate with `x-request-id`.

Billing {#billing}

Field	Meaning
`basis`	`WEIGHT`, `VOLUME`, or `DENSITY`
`calculation_model`	Pricing model used by the rate rows
`quantity_unit`	`KG`, `M3`, or `KG_PER_M3`
`supported_range`	Minimum and maximum billable quantity
`supported_range.out_of_range_behavior`	`UNAVAILABLE` — the channel cannot carry a parcel outside the range. Do not extrapolate.
`minimum`	Minimum billable quantity and whether smaller values round up (`ceil_to_minimum`)
`rounding`	Single-package and multi-package rounding steps
`volumetric_weight`	Volumetric divisor and exemption rule
`multi_package`	Per-package vs combined billing and aggregation
`overweight_warning`	Optional overweight notice

Calculation models may include FIRST_NEXT_WEIGHT, TIERED_PRICE, UNIT_PRICE_PLUS_GRADE, MULTI_LEVEL_NEXT_WEIGHT, and RANGE_FIRST_NEXT_WEIGHT. Do not re-implement the warehouse pricing engine from these rows.

Regions {#regions}

Field	Meaning
`code` / `name`	Stable region code and localized name
`match_type`	`COUNTRY_REGION` or `POSTAL_CODE`
`countries`	ISO country codes covered by this region
`postal_code_required`	When `true`, send `postal_code` to quotes
`reference_transit_time`	Display text plus optional min/max business days
`areas`	Optional finer-grained area list. The catalog does not expose the full postal-rule database.

Value-added services {#value-added-services}

Use value_added_services[].code in services.channel[] on Shipping quotes.

Field	Meaning
`code`	Stable service code
`request_mode`	`MANDATORY` (always applied) or `OPTIONAL` (developer-selected)
`pricing_type`	Fixed price vs calculated (for example `CALCULATED`)
`pricing_scope`	Where the price applies (for example `REGION`)
`pricing_basis`	How the charge is computed

BASIS_POINT is a percentage basis point: 500 means 5%. The warehouse may add, remove, or adjust services during processing — see service_policy and may_be_adjusted.

Rate cards {#rate-cards}

Field	Meaning
`region_code`	Region this card belongs to
`billing_basis`	Same vocabulary as `billing.basis`
`calculation_model`	Same vocabulary as `billing.calculation_model`
`quantity_unit`	`KG`, `M3`, or `KG_PER_M3`
`price_rows`	Reference bands used to explain the model
`reference_only`	Always `true` — not a live quote

Caching {#caching}

config_updated_at changes when channel details, regions, rate cards, rules, or services change. Cache the lightweight catalog briefly, refetch expansions when this timestamp changes, and always call Shipping quotes before creating a shipment. There is no locked pricing version.

Errors {#errors}

Channel-specific ineligibility is not an HTTP error. An empty items array is a successful catalog miss.

HTTP	`error.code`	When
400	`VALIDATION_ERROR`	Invalid pagination, country syntax, or `include` value
401	`INVALID_API_KEY`	Missing or invalid Bearer token
400	`INVALID_SHIPPING_CHANNEL`	Reserved for quote/shipment calls that name an unknown channel. This list simply returns an empty `items` array.
403	`FULFILLMENT_MODE_NOT_SUPPORTED`	App uses self fulfillment
403	`WAREHOUSE_AUTH_INVALID`	Warehouse authorization is missing, rejected, or expired
422	`INVALID_COUNTRY_CODE`	Destination country is invalid or unsupported
502	`WAREHOUSE_UPSTREAM_ERROR`	Warehouse service failed; retry with backoff

There is no distinct public AUTHENTICATION_ERROR, WAREHOUSE_AUTH_REQUIRED, or WAREHOUSE_SERVICE_UNAVAILABLE code. Auth failures use 401 INVALID_API_KEY; missing warehouse bind uses 403 WAREHOUSE_AUTH_INVALID; warehouse outages use 502 WAREHOUSE_UPSTREAM_ERROR.

See Errors and Authentication.

Examples {#examples}

Lightweight catalog:

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?page=1&page_size=20" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: en"

Channels that can serve the United States, including reference pricing:

curl "https://api.hiobuy.com/v1/fulfillment/shipping/channels?country_code=US&include=regions,services,rate_cards" \
  -H "Authorization: Bearer hio_live_xxx" \
  -H "Language: zh-CN"

Next: request a destination-specific shipping quote.

Get Support

Need integration help? Contact Developer Support at support@hiobuy.com · Response within 1–2 business days

Email support