Enable label printing
Follow the steps below to allow your customers to retrieve Zonos labels from your platform.
Allow API credentials
The Zonos API is accessible by a credentialToken. Your platform will need to give customers the ability to enter their credentialToken from the Zonos Dashboard into your platform. From here, you will be able to make requests to Zonos on their behalf.
Create a shipment
In order to retrieve a label, you are required to create a shipment that the label will be associated with. Zonos manages this process with a workflow that creates shipments and labels in the same request. When performing this mutation, you do not need to pass a serviceLevel as we will use the serviceLevel used from the landedCost that is tied to the order. For the orderId, you can use the Zonos order ID or the accountOrderNumber that will likely already be in your system.
When a shipment and labels are created successfully, we will return labels as a labelImage which is a BASE64_ENCODED_IMAGE, or as a url where the label can be fetched from.
Use this workflow when you're creating a shipment for an existing order and don't need to modify item or party details. It supports optional tracking numbers, fulfillment centers, service level selection, and declared value insurance.
Shopify passes a null value for person in the origin party. As a result, orderId alone will not function for Shopify merchants — use the Advanced shipment creation tab instead and provide full party details including person.
mutation CreateShipment($input: ShipmentCreateWorkflowInput!) { shipmentCreateWorkflow(input: $input) { id status trackingDetails { number } serviceLevel { id name carrier { id name } } shipmentCartons { id carton { id width length height weight items { item id amount description label url trackingNumber id documentFilingVariable options:
- With Fulfillment Center: Add
"fulfillmentCenter": "fulfillment_center_12345"to specify the origin location - With Custom Tracking: Set
"generateLabel": falseand add"trackingNumbers": ["tracking_1", "tracking_2"] - With Service Level: Add
"serviceLevel": "dhl.express_example"to select a specific carrier service - With Declared Value Insurance: Add
"isDeclaredValue": trueto enable declared value coverage - With Special Services: See the special services guide for batteries, dry ice, dangerous goods, and signature options.
Declared value
Set "isDeclaredValue": true to enable declared value coverage for all items in your shipment. Zonos automatically claims the full value of all items submitted in the order; merchants cannot modify this amount. This sets the maximum liability the carrier will accept in case of loss, damage, or theft during transit. This feature is only supported for UPS, FedEx, and DHL shipments. Zonos automatically handles the carrier-specific implementation when you enable declared value, including the appropriate parameters in our API calls to these carriers, so you don't need to manage different carrier requirements.
UPS limitations: UPS only covers values between 100-50,000 USD and processes declared value at the carton level. For multi-carton shipments, merchants must split the shipment to designate coverage per carton. UPS also generates an additional insurance form that must be printed with the labels.
FedEx and DHL: Process declared value at the shipment level with no additional restrictions.
Special services
Use specialServices on a carton to indicate special handling requirements for batteries, dry ice, dangerous goods, or signature requirements. See the special services guide for full details and examples.
ShipStation UPS Unlock: Multipiece shipments are not supported. When an order ships in multiple boxes, the reference field is duplicated, causing order number matching to fail on the backend. Merchants needing multipiece shipments should create the label in the Zonos Dashboard instead. Single-box shipments are unaffected.
Void a shipment
In the event that a customer wants to void a shipment, you can use the following mutation that will void all labels tied to the shipment.
mutation { shipmentStatusUpdate( input: { shipment: "shipment_f1fe4dbd-e471-49fa-94e7-84e369083223" status: VOIDED note: "Voiding shipment" } ) { id status }}
Create shipments from your platform
Give customers the ability to create Zonos shipments and labels from your platform.
This guide is designed for shipping platform developers who want to integrate Zonos shipment creation capabilities into their platform for their customers. If you're already using the Zonos API and just need to create shipments for existing orders instead, see our shipment creation guide.
If you are a shipping platform that supports Zonos customers shipping internationally, integrating with Zonos for shipment creation should be a top consideration. This will allow you to offer the most seamless experience for your merchants and their customers by leveraging your platform's existing features while letting Zonos manage the creation of the shipment, label, and supporting customs documentation.
Advantages of using Zonos to create shipments include:
This guide will walk you through the steps to implement a complete end-to-end integration that will allow you to call Zonos for shipments from your platform.