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.
Mutation
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
documentFiling
}
}
}
}
Basic Variables
{
"input": {
"generateLabel": true,
"orderId": "order_12345678-1234-1234-1234-123456789abc"
}
}
With Fulfillment Center
{
"input": {
"generateLabel": true,
"orderId": "order_12345678-1234-1234-1234-123456789def",
"fulfillmentCenter": "fulfillment_center_12345"
}
}
With Custom Tracking
{
"input": {
"generateLabel": false,
"orderId": "order_12345678-1234-1234-1234-123456789ghi",
"trackingNumbers": ["tracking_example_1", "tracking_example_2"]
}
}
With Service Level
{
"input": {
"generateLabel": true,
"orderId": "order_12345678-1234-1234-1234-123456789jkl",
"serviceLevel": "dhl.express_example"
}
}
With declared value insurance
{
"input": {
"generateLabel": true,
"orderId": "order_12345678-1234-1234-1234-123456789mno",
"isDeclaredValue": true
}
}
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.
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.
Request
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.