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.
Which setup are you?
Everyone calls Zonos to create both the label and the manifest, so you never provide your own Japan Post credentials (CTID / CT password). What changes by setup is which Zonos API headers you pass — find your row below, then use the matching tab in each flow's Endpoint and authentication section.
| ↕ | Ecommerce merchant↕ | Shipping platform (BYOA)↕ | 3PL / Logistic Partner / Reseller↕ |
|---|---|---|---|
| Who you are | A brand shipping your own orders | A platform many merchants create labels through | A partner shipping on behalf of many merchant clients |
| Verified Account you set up | One Verified Account (your own) | Each merchant sets up their own; you ship on their behalf | One Verified Account used for all your shippers |
| Zonos API headers to pass | credentialToken (yours) only | credentialToken (yours) + accountKey (each merchant's) | credentialToken (yours) only |
| Whose Later Pay Number is billed postage | Yours | Each merchant's | Yours |
| Who Zonos invoices for duties | You | Each merchant | You |
BYOA (Bring Your Own Account): each merchant holds their own Japan Post Verified Account, and the platform creates labels on that merchant's behalf by passing the merchant's account key, rather than shipping under the platform's own 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.
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.