DOCS

Integrate shipment API

Landed Cost•
HomeFor logistics providers Landed Cost Integrate shipment API

Create Zonos shipments from your platform

Give customers the ability to create Zonos shipments and labels from your platform.

If you are a shipping platform that supports Zonos customers shipping internationally, tying into 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:

  • Third party billing of duties and taxes - We will ensure that you or your merchant's carrier account number is used for shipping charges while the bills for duty and tax come to Zonos.
  • Flexibility - Instead of performing dev work to ensure that you can generate compliant labels with your platform, integrate with our API and leave the ever-changing cross-border compliance to us.
  • Accurate customs documentation - When you use Zonos to generate labels, we ensure that the right details are passed to the carrier to ensure that the package clears customs quickly.

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.

Enable customers to print Zonos labels from your platform 

Follow the steps below to allow your customers to retrieve Zonos labels from your platform.

1

Allow customers to pass in their Zonos 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.

2

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.

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
mutation {
  partyCreateWorkflow(
    input: [
      {
        location: {
          administrativeArea: "Utah"
          administrativeAreaCode: "UT"
          countryCode: US
          line1: "123 Test Street"
          locality: "St George"
          postalCode: "84770"
        }
        person: {
          companyName: "test Corp"
          phone: "8018565714"
          firstName: "Tom"
        }
        type: ORIGIN
      }
      {
        location: {
          administrativeArea: "Quebec"
          administrativeAreaCode: "QC"
          countryCode: CA
          line1: "2147 Pitfield Blvd"
          locality: "Pierrefonds"
          postalCode: "H9H 3C7"
        }
        person: {
          email: "test@gmail.com"
          firstName: "firstName"
          lastName: "lastName"
          phone: "5022303021"
          companyName: "goProTest"
        }
        type: DESTINATION
      }
    ]
  ) {
    type
    id
    organization
  }
  itemCreateWorkflow(
    input: [
      {
        amount: 50
        currencyCode: USD
        countryOfOrigin: US
        quantity: 1
        metadata: { key: "tags", value: "accessory" }
        sku: "ow-accessory-gtr"
        productId: "1892949164056"
      }
    ]
  ) {
    amount
    id
    quantity
    sku
    productId
  }
  cartonsCreateWorkflow(
    input: {
      dimensionalUnit: INCH
      height: "5"
      length: "5"
      weight: "5"
      weightUnit: POUND
      width: "10"
    }
  ) {
    items {
      item {
        amount
        id
        quantity
        sku
      }
    }
    length
    width
    weight
    weightUnit
    height
    id
  }
  shipmentCreateWorkflow(
    input: { orderId: "order_f648793c-2585-4684-afa0-da1fdb0d4f94" }
  ) {
    id
    serviceLevel {
      id
      name
      carrier {
        id
        name
      }
    }

    shipmentCartons {
      id
      tracking {
        number
      }
      label {
        labelImage
        labelFileType
      }
      carton {
        id
        width
        length
        height
        weight
        items {
          item {
            id
            amount
            description
          }
        }
      }
    }
    customsDocuments {
      id
      fileType
      fileUrl
    }
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "data": {
    "shipmentCreateWorkflow": {
      "id": "shipment_90f3c62a-c50e-466c-a317-70ececb26dc4",
      "serviceLevel": {
        "id": "service_level_a7129244-7334-4e8b-8b10-6494b0e49a7d",
        "name": "UPS Worldwide Express",
        "carrier": {
          "id": "carrier_26bf7275-cac2-47b5-979a-4325fa2efa82",
          "name": "UPS"
        }
      },
      "shipmentCartons": [
        {
          "id": "shipment_carton_d254a6df-9dcd-47fc-926b-48eaeaea232c",
          "tracking": {
            "number": "1Z2030216698896462"
          },
          "label": {
            "labelImage": "{{BASE64_ENCODED_IMAGE}}",
            "labelFileType": "PDF",
            "labelAmounts": [
              {
                "amount": 41.88,
                "amountType": "QUOTE"
              }
            ]
          },
          "carton": {
            "id": "carton_0jhg9mxk431q7",
            "width": 10.0,
            "length": 5.0,
            "height": 5.0,
            "weight": 5.0,
            "items": [
              {
                "item": {
                  "id": "item_0jhg9mxdwm77w",
                  "amount": 50,
                  "description": null
                }
              }
            ]
          }
        }
      ],
      "customsDocuments": [
        {
          "id": "customs_doc_d8bedf7a-2de0-4729-8bdd-ebd901b67127",
          "fileType": "PDF",
          "fileUrl": "https://prod-zonos-shipping-label.s3.us-east-2.amazonaws.com/organization_a61090a2-d18b-415c-9870-03b9087cbf2d/shipment_90f3c62a-c50e-466c-a317-70ececb26dc4/customs/International_Forms.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250117T231615Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAR3GS2GP6V4LZE3OI%2F20250117%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Expires=14400&X-Amz-Signature=6c17e358a038c3cd7d61391302909ee503344249405974e490d9b46051c79dba"
        }
      ]
    }
  }
}
3

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

1
2
3
4
5
6
7
8
9
10
11
12
mutation {
  shipmentStatusUpdate(
    input: {
      shipment: "shipment_f1fe4dbd-e471-49fa-94e7-84e369083223"
      status: VOIDED
      note: "Voiding shipment"
    }
  ) {
    id
    status
  }
}

Was this page helpful?

Questions?

Contact us.
© 2025 Zonoszonos.com
On this page:
  • Create Zonos shipments from your platform
  • Enable customers to print Zonos labels from your platform
  • Allow customers to pass in their Zonos API credentials
  • Create a shipment
  • Void a shipment