Create a single shipment

CreateDeclarationShipment chains together seven *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
declarationCreateWorkflow      → create the customs declaration
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 declaration needs the landed cost; the label needs everything). Bundling them into a single GraphQL document keeps the data consistent and avoids six extra round trips.

Endpoint 

URL:

https://api.zonos.com/graphql

Headers:

credentialToken: {{YOUR_API_TOKEN}}
accountKey:      {{SHIPPER_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 7. 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. declarationCreateWorkflow

Creates a Declaration — an identifier required to clear the package into the destination country under current customs regulations.

The response returns a Declaration with an id, source, and status, or a list of errors. The id is what's needed for the shipment to be accepted; nothing else from this step is consumed by the caller in this flow.

7. 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:

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.

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.
• Declaration errors (e.g. unsupported source) surface inside declarationCreateWorkflow.errors rather than the top-level errors array, so always check both.
• 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.

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, DECLARATION_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.