Using Zonos with the Japan Post My Page API

This guide is for teams that already integrate with the Japan Post My Page Web API to create labels (operation ctCode=52). For U.S.-bound parcels, which now require duties to be prepaid, you create the label through Zonos. Zonos is an extension of the My Page workflow: it calls the My Page Label API (ctCode=52) on your behalf, adds the U.S. duty Declaration ID and DDP marking, and returns the My Page label and tracking number to you. Japan Post still produces the label and bills your postage through your Later Pay Number.

In short: you keep building on My Page, and Zonos handles the U.S. duty layer for shipments bound for the United States.

If you're integrating for the first time, start with Create a single shipment.

How Zonos fits in 

For a U.S.-bound parcel, you send the shipment to the Zonos CreateDeclarationShipment GraphQL workflow instead of calling My Page directly. In that single request, Zonos:

1. Calls the Japan Post Label API (ctCode=52) on your behalf, using your Verified Account's Later Pay Numbers so postage is still billed to your Japan Post account.
2. Creates the U.S. duty Declaration ID and links it to the tracking number.
3. Adds the DDP marking to the label.
4. Returns the Japan Post label and tracking number to you.

CreateDeclarationShipment chains seven steps. The same data you already assemble for a ctCode=52 request is distributed across them:

• Sender / receiver → the partyCreateWorkflow ORIGIN and DESTINATION parties.
• Items → itemCreateWorkflow (the line items inside shipmentCartons).
• Packaging and weight → cartonsCreateWorkflow.
• Service, handling, and customs flags → shipmentCreateWorkflow.

How your My Page fields map to Zonos 

Each table shows where a Japan Post My Page ctCode=52 parameter goes in the Zonos workflow. For full field details, types, and which fields are required, see Create a single shipment.

Service and handling → shipmentCreateWorkflow

Sender → partyCreateWorkflow (ORIGIN party)

Receiver → partyCreateWorkflow (DESTINATION party)

The receiver to_* parameters map to the DESTINATION party the same way the sender fields do.

Items → itemCreateWorkflow

Conversions to know 

These are the transforms that most often need attention:

• Service level replaces sendType + transType. Pick the single Zonos japan_post.* service level that matches the mail service and transport you send today as two separate parameters.
• Insured value (declaredValue) must be JPY, whole yen. Other currencies or fractional yen will be rejected.
• Weight is sent to Japan Post in grams. Provide weight + weightUnit on the carton; Zonos converts.
• Item customs descriptions are limited to 85 half-width characters.
• All address fields must be in English (Roman) characters.

Verify your U.S. labels 

When you create a U.S. label through Zonos, confirm it worked end to end:

1. The workflow returns a tracking number and label. Check shipmentCreateWorkflow.trackingDetails.number and shipmentCartons[].label.url in the response.
2. A Declaration ID was created and linked. The shipment is duty-prepaid only when the Declaration ID is linked to the tracking number — Zonos does this inside the same request.
3. DDP is printed on the label. Open the returned label and confirm the DDP marking is present.
4. The shipment appears in your Zonos Dashboard under your Verified Account.
5. For batch dispatch, confirm the consolidation closes and returns the Japan Post dispatch slip (Code 61). See Batch dispatch (consolidation).
6. Compare against a My Page label. Create the same shipment both ways and confirm the service level, weight, declared value, and item details match on the printed label.

Related 

• Create a single shipment — full field reference for the CreateDeclarationShipment workflow.
• Batch dispatch (consolidation) — bundle the day's parcels into one Japan Post dispatch slip.