A developer reference implementation for discovering available shipping channels, inspecting channel details, and estimating international shipping costs with the HIOBuy Fulfillment API.
Built with Next.js and designed to keep your HIOBuy API key server-side.
HioBuy Shipping Quotes Live Demo
This repository demonstrates three core shipping APIs:
- Discover shipping channels available to your warehouse.
- Inspect channel regions, transit time, billing configuration, services, rate cards, and channel rules.
- Estimate international shipping costs using destination, package, declared-value, and service data.
Shipment creation, payment, and tracking are intentionally outside the scope of this demo.
- Lists shipping channels available to the warehouse associated with the API key.
- Discovers destination countries dynamically from available channel regions.
- Displays structured channel configuration and reference transit times.
- Calculates shipping estimates using declared package data.
- Supports price and transit-time sorting in ascending or descending order.
- Supports optional channel services and declared-value-based services.
- Keeps
HIOBUY_API_KEYinside server-only Next.js Route Handlers. - Converts CNY API amounts into a configurable display currency.
- Handles both HTTP transport errors and HIOBuy business-level errors.
- Hides unavailable quotes from shopper-facing results while preserving the API contract server-side.
Requirements:
- Node.js 20 or newer
- pnpm
- A HIOBuy Developer API key
Clone the repository:
git clone https://github.com/hiobuy/shipping-quotes.git
cd shipping-quotesCreate your local environment file and start the development server:
cp .env.example .env.local
pnpm install
pnpm devAdd your sandbox or test API key to .env.local:
HIOBUY_API_KEY=your_api_key_hereThen open:
http://localhost:3000
| Variable | Required | Example | Purpose |
|---|---|---|---|
HIOBUY_API_KEY |
Yes | your_api_key_here |
Server-only HIOBuy Developer API key. |
HIOBUY_API_BASE_URL |
No | https://api.hiobuy.com |
HIOBuy API origin. |
HIOBUY_DEFAULT_LANGUAGE |
No | en |
Value sent in the Language request header. |
SHIPPING_DISPLAY_CURRENCY |
No | USD |
ISO 4217 currency displayed by the demo UI. |
SHIPPING_CNY_EXCHANGE_RATE |
No | 0.14 |
Target-currency units for one CNY. |
HIOBuy shipping money objects use CNY minor units.
For example:
{
"amount": 1250,
"currency": "CNY"
}represents:
¥12.50
If:
SHIPPING_CNY_EXCHANGE_RATE=0.14the demo interprets this as:
1 CNY = 0.14 USD
Display conversion:
(CNY minor units ÷ 100) × exchange rate
Declared-value conversion works in the opposite direction:
entered display currency ÷ exchange rate = CNY
The CNY result is converted to minor units before being submitted to the API.
For example, with a 0.14 USD exchange rate:
14 USD → 100 CNY → 10000 CNY minor units
The configured exchange rate is for demonstration purposes only. It is not a live foreign-exchange feed.
| Purpose | HIOBuy API | Local demo endpoint |
|---|---|---|
| Channel catalog | GET /v1/fulfillment/shipping/channels |
GET /api/shipping/channels |
| Channel detail | GET /v1/fulfillment/shipping/channels/{shipping_channel_code} |
GET /api/shipping/channels/{shipping_channel_code} |
| Shipping estimate | POST /v1/fulfillment/shipping/quotes |
POST /api/shipping/quotes |
The browser never calls the HIOBuy API directly.
Browser
│
▼
Next.js /api/shipping/*
│
│ Authorization: Bearer <server-only API key>
▼
HIOBuy Fulfillment API
│
▼
https://api.hiobuy.com/v1/fulfillment/shipping/*
HIOBUY_API_KEY remains on the server and is never exposed to browser JavaScript.
Channel codes are URL-encoded before being passed into the public channel-detail path.
The destination selector is generated from the active fulfillment locations rather than from a hard-coded global country list.
The server requests:
GET /v1/fulfillment/locations?status=ACTIVEIt then collects, validates, normalizes, and deduplicates:
data[].supported_destinations[]
Country values remain ISO 3166-1 alpha-2 codes. The browser may use Intl.DisplayNames to display localized country names.
This represents destination coverage reported by the active fulfillment locations visible to the warehouse associated with the current API key.
It does not guarantee that a particular shipment can use a destination.
Actual availability may depend on:
- postal code
- package weight
- package dimensions
- product characteristics
- selected services
- channel rules
- warehouse configuration
POST /v1/fulfillment/shipping/quotes is authoritative for shipment-specific availability and pricing.
The channel detail view can display:
- warehouse identity
- supported regions and countries
- channel capabilities
- billing basis and billing model
- quantity unit and supported range
- minimum charges
- rounding rules
- multi-package scope
- volumetric-weight rules
- structured reference transit time
- complete reference price rows, grouped by billing range where required
- available services
- channel rule details
By default, the demo requests:
regions,services,rate_cards,rules
The detail request loads these expansions together so the dialog does not require a second action to reveal its rules.
Structured transit-time fields are preferred:
reference_transit_time.min_business_days
reference_transit_time.max_business_days
A single value is displayed as:
5 business days
A range is displayed as:
5–8 business days
The compatibility text value is used only when structured transit-time values are unavailable.
Transit times are estimates and should not be treated as guaranteed delivery dates.
Shipping quotes are shipment-specific.
Reference rate cards are useful for understanding a channel's pricing structure, but they should not be used as the final shipping price.
Use:
POST /v1/fulfillment/shipping/quotesfor shipment-specific availability and estimated charges.
Quotes may depend on:
- destination
- package weight
- package dimensions
- chargeable weight
- declared value
- selected services
- channel rules
Final shipping charges may change after warehouse measurement, packing, or service review.
Channel services may be:
MANDATORY
or:
OPTIONAL
Percentage values are already expressed as percentage points.
For example:
10
means:
10%
not 1000%.
Service pricing may be based on:
- base freight
- declared value
- fixed amount per shipment
- fixed amount per box
- chargeable-weight units
If a selected service requires declared value, the demo requires the user to provide it before requesting a quote.
The quote request always sends:
services.channel
When all optional services are removed, the demo sends an empty array rather than omitting the field. This prevents provider defaults from being unintentionally reapplied.
The demo understands the following rule aggregation modes.
Every matched and calculable charge is added to the quote.
Matched charges are compared and only the highest applicable charge is used.
Equal highest amounts are considered equivalent.
cap: null
or:
cap.amount: 0
means that no cap is applied.
Pending or inapplicable rules do not contribute to the quote total.
HIOBuy transport errors use standard HTTP status codes and the standard API error object.
Some warehouse business failures may return HTTP 200 with:
{
"success": false
}The server client therefore checks both:
- HTTP status
- response body
A missing, invisible, or country-filtered shipping channel is exposed locally as:
{
"error": {
"code": "CHANNEL_NOT_FOUND",
"message": "Shipping channel not found.",
"request_id": "..."
}
}The demo intentionally keeps error handling on the server so developers have one normalized browser-facing error path.
src/
app/
api/
shipping/ # Server-only Route Handlers
components/
channel-details.tsx # Channel configuration/details
shipping-calculator.tsx # Shipping quote UI
lib/
hiobuy.ts # Authenticated HIOBuy server client
shipping-api-contract.ts # API contract helpers
shipping-format.ts # Money, transit and service formatting
shipping-types.ts # Normalized public API types
tests/
shipping-contract.test.ts
The demo intentionally proxies HIOBuy requests through server-side Next.js Route Handlers.
For production applications:
- Never expose
HIOBUY_API_KEYto the browser. - Never prefix the API key with
NEXT_PUBLIC_. - Store production keys in your deployment platform's secret manager.
- Do not log authorization headers or environment variables.
- Keep
.env.local,.next, and logs out of Git. - Apply application-level rate limiting before exposing public proxy endpoints.
- Add appropriate monitoring and abuse protection.
This repository is a reference implementation, not a production shipping application.
Keep in mind:
- Shipping quotes are estimates based on declared shipment data.
- Final charges may change after warehouse measurement and packing.
- Transit times are estimates.
- Destination availability is derived from channels visible to the current warehouse and API key and should not be treated as a complete list of globally supported destinations.
- The configured exchange rate is static and may become stale.
- Reference rate cards explain configured pricing but must not be used to reproduce final quote calculations in the browser.
- Production applications should implement their own authentication, authorization, rate limiting, monitoring, and business rules.
For the complete API contract and additional HIOBuy capabilities, see:
This repository focuses specifically on shipping channel discovery and shipping quotes.
Other HIOBuy API capabilities, including shipment lifecycle and tracking, may be provided as separate examples so each repository remains small, focused, and easy to understand.
This project is licensed under the MIT License.