unit_price without declared_currency is now read as USD
Until now, a request that omitted declared_currency was read as HKD. If a caller's unit_price actually held a USD amount without declaring the currency, it was read as HKD instead, so the declared value ended up at roughly 1/7.8 of what was intended — typically without the request being rejected, though a low enough HKD-read unit_price (for example 0.01) could round to USD 0.00 and return 400. Callers whose unit_price was genuinely an HKD amount were unaffected. The web and bulk-upload order flows have accepted USD only since 2026-09-07, and USD is the declaration currency we recommend for the API. The API's reading of unit_price now matches.
- changed
POST /api/v1/shipments: when declared_currency is omitted and any item carries unit_price, the shipment is now read as USD — unit_price is a USD amount (previously HKD). Items with no unit price are still accepted and declared at 0. As with an explicit declared_currency: "USD", an unresolvable exchange rate now returns 503 FX_RATE_UNAVAILABLE (1500018) for these requests; it is safe to retry with the same Idempotency-Key. Because the declared value is read differently, value-based surcharges and pricing_snapshot.total_hkd can differ, a destination's declared-value cap can apply, and a create bound with expected_total_hkd can return 409 PRICING_QUOTE_CHANGED if that total was quoted for a different declared value. If your integration sends HKD amounts in unit_price without declared_currency, add declared_currency: "HKD" or switch to unit_price_hkd — otherwise those amounts will be read as USD, roughly 7.8× higher. - changed
POST /api/v1/shipments: when declared_currency is omitted, mixing unit_price and unit_price_hkd across the items of one shipment now returns 400 INVALID_FIELD; the message names the items involved. A shipment has one declared currency: use the same price field on every item, or send declared_currency explicitly (with "HKD", both fields are HKD amounts, as before). - changedNot affected:
unit_price_hkd is always HKD, so requests whose items use only unit_price_hkd (or carry no unit price) with declared_currency omitted are handled as before; requests that send declared_currency explicitly ("USD" or "HKD") are handled as before, including the rule that an explicit "USD" requires unit_price on every item. We recommend always sending declared_currency. - changedMCP
create_shipment forwards to this endpoint and follows the same rules; its field descriptions now say so. MCP clients that cached the previous tool descriptions should reconnect to pick them up.