Already create labels with the Japan Post My Page API? Keep your integration — add Zonos for duty-prepaid U.S. labels.
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.
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:
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.
Creates the U.S. duty Declaration ID and links it to the tracking number.
Adds the DDP marking to the label.
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 partyCreateWorkflowORIGIN and DESTINATION parties.
Items → itemCreateWorkflow (the line items inside shipmentCartons).
Packaging and weight → cartonsCreateWorkflow.
Service, handling, and customs flags → shipmentCreateWorkflow.
Zonos handles these for you
You don't send Japan Post credentials or the operation code (ctCode, ctId, ctPw), the ship date (sendDate), or the DDP declaration remarks. Zonos sets these automatically when it calls My Page.
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.
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.
When you create a U.S. label through Zonos, confirm it worked end to end:
The workflow returns a tracking number and label. Check shipmentCreateWorkflow.trackingDetails.number and shipmentCartons[].label.url in the response.
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.
DDP is printed on the label. Open the returned label and confirm the DDP marking is present.
The shipment appears in your Zonos Dashboard under your Verified Account.
For batch dispatch, confirm the consolidation closes and returns the Japan Post dispatch slip (Code 61). See Batch dispatch (consolidation).
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.
Test before you go live
Validate the full flow on a test shipment before sending production U.S. volume through Zonos. Your My Page integration stays in place for everything else.
Using Zonos with the My Page API
Using Zonos with the Japan Post My Page API
Already create labels with the Japan Post My Page API? Keep your integration — add Zonos for duty-prepaid U.S. labels.
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
CreateDeclarationShipmentGraphQL workflow instead of calling My Page directly. In that single request, Zonos:ctCode=52) on your behalf, using your Verified Account's Later Pay Numbers so postage is still billed to your Japan Post account.CreateDeclarationShipmentchains seven steps. The same data you already assemble for actCode=52request is distributed across them:partyCreateWorkflowORIGINandDESTINATIONparties.itemCreateWorkflow(the line items insideshipmentCartons).cartonsCreateWorkflow.shipmentCreateWorkflow.You don't send Japan Post credentials or the operation code (
ctCode,ctId,ctPw), the ship date (sendDate), or the DDP declaration remarks. Zonos sets these automatically when it calls My Page.How your My Page fields map to Zonos
Each table shows where a Japan Post My Page
ctCode=52parameter goes in the Zonos workflow. For full field details, types, and which fields are required, see Create a single shipment.Service and handling →
shipmentCreateWorkflowsendType+transTypeserviceLevel(andshipmentRatingCreateWorkflow.serviceLevelCode)japan_post.air.parcel. Must be ajapan_post.*service level.pkgTypecontentsTypeSALE_OF_GOODS,ECOMMERCE_GOODS,COMMERCIAL_GOODS,COMMERCIAL_SAMPLE,RETURNED_GOODS,GIFT,DOCUMENTS, orOTHER.senderInstructionnonDelivery.optionRETURN_AFTER_RETENTION,RETURN_IMMEDIATELY,FORWARD, orABANDON. Zonos splits My Page's single "return" instruction into two values.fw_TransTypenonDelivery.transportMethodAIRorMOST_ECONOMICAL. Applies to the twoRETURN_*options.noCmisNonCommercialtrue/false.damgesdeclaredValuetotalWeightcartonsCreateWorkflow.weight+weightUnitSender →
partyCreateWorkflow(ORIGINparty)from_namperson.firstName+person.lastNamefrom_companyNameperson.companyNamefrom_postallocation.postalCodefrom_add1/from_add2/from_add3location.line1/location.line2/location.localityfrom_preflocation.administrativeAreaCodefrom_telperson.phoneReceiver →
partyCreateWorkflow(DESTINATIONparty)The receiver
to_*parameters map to theDESTINATIONparty the same way the sender fields do.to_namperson.firstName+person.lastNameto_companyNameperson.companyNameto_couCdlocation.countryCodeUSorPR.to_add1/to_add2/to_add3location.line1/location.line2/location.localitylocation.postalCode/location.administrativeAreaCode/person.phoneItems →
itemCreateWorkflowitem_pkgcustomsDescriptionitem_hsCodehsCodeitem_numquantityitem_weightmeasurements(per-unit weight)item_costamountitem_curUnitcurrencyCodeConversions to know
These are the transforms that most often need attention:
sendType+transType. Pick the single Zonosjapan_post.*service level that matches the mail service and transport you send today as two separate parameters.declaredValue) must be JPY, whole yen. Other currencies or fractional yen will be rejected.weight+weightUniton the carton; Zonos converts.Verify your U.S. labels
When you create a U.S. label through Zonos, confirm it worked end to end:
shipmentCreateWorkflow.trackingDetails.numberandshipmentCartons[].label.urlin the response.Validate the full flow on a test shipment before sending production U.S. volume through Zonos. Your My Page integration stays in place for everything else.
Related
CreateDeclarationShipmentworkflow.Was this page helpful?