How the Zonos + Japan Post API model works
Japan Post Verified Account merchants call Zonos directly. Zonos uses its own credentials with Japan Post and includes your Later Pay Number on every label so postage is billed to your account.
In a single GraphQL request, Zonos:
- Validates your Verified Account and Later Pay Numbers.
- Calls the Japan Post Label API (code 52) on your behalf to generate the label and tracking number.
- Creates a Declaration ID for U.S. duty prepayment.
- Links the Declaration ID to the tracking number via
declarationShipmentCreate. - Returns the label, tracking number, and shipment record back to you.
You do not need your own Japan Post API credentials (CTID / CT password). You do need your Japan Post Later Pay Numbers (後納お客様番号) connected to your Zonos Verified Account.
Two API flows
There are two integration patterns depending on how you dispatch parcels.
Create a single shipment
The foundational chain. One GraphQL request takes a shipment from raw inputs (parties, items, packaging) all the way through to a printable Japan Post label. Use this if you ship parcels individually as orders come in.
Batch dispatch (consolidation)
The deferred-payment batch flow. Open a consolidation in the morning, attach shipments to it across the day using the single-shipment chain, then close the consolidation at end-of-day to get one Japan Post dispatch slip covering the whole batch. Use this if you settle Japan Post postage in one transaction at end-of-day rather than parcel-by-parcel.
Already using the Japan Post My Page API?
If you currently create labels with the Japan Post My Page API (ctCode=52), you can keep that integration and add Zonos for duty-prepaid U.S. labels. See Using Zonos with the My Page API for a field-by-field mapping and a verification checklist.
Endpoint and authentication
Both flows use the same endpoint and headers.
URL:
https://api.zonos.com/graphql
Headers:
credentialToken: {{YOUR_API_TOKEN}}
accountKey: {{SHIPPER_API_TOKEN}}
Create labels via API
Integrate your fulfillment system with the Zonos GraphQL API to create duty-prepaid Japan Post labels.
This section is for engineering teams who are building a programmatic Japan Post label workflow that will use Verified Accounts. If you're a small or mid-size shipper without development resources, see Create labels in Dashboard instead.