Create a single shipment

CreateDeclarationShipment chains together six *Workflow mutations into a single GraphQL request. Each step builds on the data the previous steps provided, and all of them are submitted together so a complete shipment can be created in one round trip:

partyCreateWorkflow            → describe origin + destination parties
itemCreateWorkflow             → describe the line items
cartonsCreateWorkflow          → describe the physical packaging
shipmentRatingCreateWorkflow   → record the carrier rate quote
landedCostCalculateWorkflow    → calculate duties / taxes / fees
shipmentCreateWorkflow         → create the shipment + label

The Workflow mutations are designed to be chained: you don't need to thread IDs from one step into the next, and you don't need to send a separate request per step. Submit the whole document, get the final Shipment back.

When the serviceLevel on the final step is a Japan Post service level (japan_post.*), Zonos calls the Japan Post Label API (code 52) on your behalf using your Verified Account's Later Pay Numbers, generates the label and tracking number, creates the Declaration ID, and links them — all inside that final shipmentCreateWorkflow step.

Why one mutation? Each step depends on the previous one (landed cost needs the items + parties; the label needs everything). Bundling them into a single GraphQL document keeps the data consistent and avoids five extra round trips.

Endpoint and authentication 

The requests in this chain all use the same endpoint. What you pass in the headers depends on your setup — pick your tab.

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}

Example request 

A complete CreateDeclarationShipment request you can copy and adapt — the mutation, its variables, and the response — for a single Japan Post parcel shipped DDP to the U.S. Each input is broken down in the step-by-step section below.

Step-by-step 

The Status column on each table below uses these terms:

• Required — the request fails without it.
• Required for label — optional in the GraphQL schema, but needed to produce a valid Japan Post U.S. label.
• Conditional — required depending on another field (noted inline).
• Recommended — optional, but drives accurate duties and taxes.
• Optional — not needed.

1. partyCreateWorkflow

Creates the parties involved in the shipment — at minimum an ORIGIN (where the shipment ships from) and a DESTINATION (the buyer / consignee).

Example payload:

[
  { "type": "DESTINATION", "location": { "countryCode": "US" }, "person": {} },
  { "type": "ORIGIN", "location": { "countryCode": "JP" }, "person": {} }
]

The response returns the created Party IDs and resolved address fields.

2. itemCreateWorkflow

Creates the line items that make up the shipment. These are the SKUs that will appear on the commercial invoice and drive the landed-cost calculation.

The HS code, country of origin, and amount are the three fields that most influence the duty/tax outcome in step 5.

3. cartonsCreateWorkflow

Creates the physical packages — the boxes, polybags, or letters that will hold the items.

Each carton becomes one parcel on the carrier label in step 6. Multiple cartons → multi-piece shipment with one tracking number per carton.

4. shipmentRatingCreateWorkflow

Records the rate quote the merchant is charging the buyer for shipping.

This is the rate the buyer was quoted at checkout. It feeds into the landed-cost calculation as the "shipping" subtotal so duties and taxes are computed against the correct CIF value.

5. landedCostCalculateWorkflow

Runs the duties, taxes, and fees calculation for the destination country. Uses the items, parties, and shipping cost from the prior steps.

The response includes amountSubtotals (duties, taxes, fees, shipping, landedCostTotal) — these are the numbers you display to the buyer at checkout and that get printed on the commercial invoice.

6. shipmentCreateWorkflow

The terminal step — creates the Shipment entity, generates the carrier label, and (optionally) the commercial invoice / packing slip.

For Japan Post Verified Accounts, this is also where Zonos calls the Japan Post Label API (code 52) on your behalf, injects your Later Pay Numbers, creates the Declaration ID, and links the Declaration ID to the tracking number returned by Japan Post.

Key fields:

On contentsType, the two most common values for Verified Account traffic are ECOMMERCE_GOODS (sold to a consumer, BtoC) and COMMERCIAL_GOODS (sold between businesses, BtoB). These set the pkgType Zonos sends on the Japan Post label call, so the choice changes what prints on the customs declaration — it isn't just a label.

nonDelivery sub-input

Tells Japan Post what to do with the parcel if it can't be delivered — refused by the consignee, rejected at the border, or undeliverable as addressed.

option accepts exactly these four values. There is no RETURN value — use RETURN_AFTER_RETENTION or RETURN_IMMEDIATELY to pick when the parcel comes back.

The API exposes both return variants separately; the Dashboard's Return option covers both.

transportMethod accepts AIR or MOST_ECONOMICAL, and sets how a returned parcel travels back. It only applies to the two RETURN_* options — the Dashboard shows the matching Return method field only when Return is selected.

{
  "nonDelivery": {
    "option": "RETURN_AFTER_RETENTION",
    "transportMethod": "MOST_ECONOMICAL"
  }
}

The If undeliverable picker in the Dashboard Create label dialog writes this same field, so a label created in the Dashboard and a label created through the API behave identically.

references sub-input

These fields print on the carrier label and/or commercial invoice. Use them to surface PO numbers, license numbers, and free-text remarks the consignee or customs authority needs to see.

Response

The interesting fields on the returned Shipment are:

{
  id
  trackingDetails {
    number
  }
  shipmentCartons {
    label {
      url
      labelImage
    }
  }
}

trackingDetails.number is the Japan Post tracking number.

The label object can return the label two ways — request whichever fits your workflow (or both):

Select only the fields you need. Requesting url keeps the response small; requesting labelImage returns the full label inline so you don't need a second round trip to fetch it. The example above requests url.

Japan Post service levels 

Pass one of these codes as serviceLevelCode in shipmentRatingCreateWorkflow.

Service level codes use dots, not underscores. You may see the underscore form (japan_post_air_parcel) in error messages and internal references, but it is not valid input.

Air services

Surface services

Choosing between similar services

Small packet vs. International Air Packet. Both are capped at 2 kg. japan_post.air.packet is Japan Post's tracked small-packet service. japan_post.air.small_packet is the untracked equivalent. If you need tracking on a lightweight parcel, use japan_post.air.packet.

Registered variants. For letters and printed matter, tracking is added by the registered (書留) version of the service. japan_post.air.printed_matter and japan_post.air.letter do not include it on their own.

Deprecated codes

japan_post.air.epacket_light was International e-Packet Light. Japan Post renamed the service to International Air Packet on June 1, 2026, and expanded it to all countries and regions. The service itself is unchanged.

The old code still resolves so existing integrations keep working, but use japan_post.air.packet for new work.

Transport-mode codes

japan_post.air, japan_post.surface, japan_post.economy_air, and japan_post.custom also resolve, but they identify a transport mode or a fallback rather than a specific mail product. Use one of the service codes above for normal shipments.

Validate the code you send

An unrecognized serviceLevelCode does not raise an error. The request returns HTTP 200 with no errors array, serviceLevel comes back as null, and shipping drops out of the landed cost total — so the response looks correct while the amounts are wrong.

Always assert that shipmentRatingCreateWorkflow.serviceLevel is non-null before relying on the totals.

To pull the current list at any time:

{
  serviceLevels(carrier: "carrier_00004c9b-9431-4518-bfbc-b9f8476335b1") {
    code
    name
  }
}

This query takes the carrier ID. Passing the carrier code japan_post returns an empty list with no error.

Error handling 

• Validation errors (missing required fields, invalid country codes, etc.) come back in the standard GraphQL errors array and abort the rest of the chain.
• Japan Post errors (label generation failure, invalid address, etc.) surface as GraphQL errors on shipmentCreateWorkflow. If a retry is needed, contact support — the recommended path is to resubmit the full mutation with corrected input.

VALIDATION_INVALID_TYPE_VARIABLE

{
  "errors": [
    {
      "message": "invalid type for variable: 'shipmentInput'",
      "extensions": {
        "name": "shipmentInput",
        "code": "VALIDATION_INVALID_TYPE_VARIABLE"
      }
    }
  ]
}

This error names the whole variable, not the field that's actually wrong. It almost always means one enum value inside that variable isn't a member of its enum — most often nonDelivery.option, contentsType, or serviceLevel.

It is not a JSON-typing problem. Quoting or unquoting your booleans and numbers won't change it, because the payload never gets that far — the enum is rejected first.

To find the bad field, check every enum-valued field in the variable against its accepted values:

The full enum members for any input are listed on its type page in the API reference.

Permissions 

Each step is independently secured. Your API key must hold the write scope for each entity in the chain (ITEM_WRITE, CARTON_WRITE, SHIPMENT_RATING_WRITE, LANDED_COST_WRITE, SHIPMENT_WRITE). The standard merchant role on a Verified Account grants all of these.

Next steps 

• Batch dispatch (consolidation) — bundle the day's parcels into one Japan Post deferred-payment dispatch slip.