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
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" }
        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"
          metadata: { key: "key", value: "value" }
        }
        type: DESTINATION
      }
    ]
  ) {
    type
    id
    organization
  }
  itemCreateWorkflow(
    input: {
      amount: "50"
      currencyCode: USD
      quantity: 1
      sku: "test1"
      description: "shoes"
      hsCode: "670121"
    }
  ) {
    amount
    id
    sku
  }
  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_627db90e-d2e2-4499-b388-bfd5d8d33e18" }
  ) {
    id
    status
    shipmentCartons {
      id
      label {
        id
        url
        labelAmounts {
          amount
          amountType
        }
      }
    }
    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
{
  "data": {
    "shipmentCreateWorkflow": {
      "id": "shipment_cd535d6f-c92a-41a9-ae70-f6e67ed30dc9",
      "status": "CREATED"
    },
    "shipmentCartons": [
      {
        "id": "label_171c7cf5-b005-45cb-bac4-2bfc141dbacb",
        "trackingNumber": "794602938880",
        "status": "CREATED",
        "documentFiling": "ELECTRONIC",
        "labelImage": "{{BASE64_ENCODED_IMAGE}}",
        "labelAmounts": [
          {
            "amount": 137.87,
            "amountType": "QUOTE"
          }
        ],
        "shipmentCarton": "shipment_carton_480d776e-48d8-4699-9b37-bc26c7d0cd1b",
        "statusTransitions": [
          {
            "changedAt": "2024-02-09T18:54:37.158Z",
            "note": "Label created",
            "status": "CREATED"
          }
        ]
      }
    ]
  }
}
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