DOCS

Integrate label api

/

Retrieve Zonos labels from your plaftorm

Give customers the ability to print Zonos-generated labels from your platform.

If you are a shipping platform that supports Zonos customers shipping internationally, tying into Zonos for shipping labels 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 label and supporting customs documentation.

Advantages of using Zonos to generate labels include:

  • Third party billing of duties and taxes - We will ensure that you or your merchants 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 labels from your shipping 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

Retrieve Zonos order details

To pull in order details, you have the abilty to query all orders or match existing orders on the accountOrderNumber

Query all orders
Match an existing order

If you want to pull in all Zonos orders for a shared customer, you can use the following query:

Query

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
query {
  orders(first: 10) {
    edges {
      cursor
      node {
        id
        accountOrderNumber
        landedCosts {
          amountSubtotals {
            duties
            fees
            items
            landedCostTotal
            shipping
            taxes
          }
          id
          landedCostGuaranteeCode
        }
      }
    }
  }
}

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
{
  "data": {
    "orders": {
      "edges": [
        {
          "cursor": "c2ltcGxlLW9mZnNldC1jdXJzb3Iw",
          "node": {
            "id": "order_d221c2d2-a26a-46b9-a5ee-c9984381944f",
            "accountOrderNumber": "31124",
            "landedCosts": [
              {
                "amountSubtotals": {
                  "duties": 0.0,
                  "fees": 8.19,
                  "items": 50.0,
                  "landedCostTotal": 51.15,
                  "shipping": 176.11,
                  "taxes": 42.96
                },
                "id": "landed_cost_9cbbb49c-3742-4d25-b79d-d8b2054ad15a",
                "landedCostGuaranteeCode": "ZONOS"
              }
            ]
          }
        }
      ]
    }
  }
}
3

Retrieve Zonos service levels

To view available service levels for a merchant, you can use the following query. Zonos uses the term shippingProfile when referring to carrier services that are enabled and in use by our merchants. The serviceLevels listed under each shippingProfile can then be used when creating a label in your platform.

Query

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
query {
  shippingProfiles {
    customServiceLevelCode
    id
    landedCostMethod
    serviceLevel {
      availability
      carrier {
        name
      }
      carrierApiCode
      carrierLabelApiCode
      code
      deliveryType
      id
      name
    }
  }
}

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": {
    "shippingProfiles": [
      {
        "customServiceLevelCode": "USPS_PRIORITY_MAIL_INTERNATIONAL",
        "id": "shipping_profile_457d4bb6-ef05-4e7e-939e-2a5b7fb2dccf",
        "landedCostMethod": "DAP_FORCED",
        "serviceLevel": {
          "availability": "GENERAL",
          "carrier": {
            "name": "USPS"
          },
          "carrierApiCode": "2",
          "carrierLabelApiCode": "691",
          "code": "usps.priority_intl",
          "deliveryType": null,
          "id": "service_level_56489602-42fb-4f47-afb3-2135e87d215d",
          "name": "USPS Priority Int'l"
        }
      }
    ]
  }
}
4

Create a label

In order to create 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 these mutations, it is best to do so with the serviceLevel that was pulled from the landedCost that is tied to the order. Zonos will return labels as a labelImage which is a BASE64_ENCODED_IMAGE, or as a url where the label can be fetched from.

Complete shipment
Split shipment

Use this mutation if you are fulfilling all items on an order.

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
mutation ShipmentLabelWorkflow(
  $shipmentWorkflowInput: ShipmentCreateWorkflowInput!
  $labelInput: LabelCreateWorkflowInput!
) {
  shipmentCreateWorkflow(input: $shipmentWorkflowInput) {
    id
    status
  }
  labelCreateWorkflow(input: $labelInput) {
    id
    trackingNumber
    status
    documentFiling
    labelImage
    labelAmounts {
      amount
      amountType
    }
    shipmentCarton
    statusTransitions {
      changedAt
      note
      status
    }
  }
}

Variables

1
2
3
4
5
6
7
8
9
10
{
  "shipmentWorkflowInput": {
    "orderId": "order_9da73be6-d574-4403-9470-8b352e74cf4a",
    "serviceLevel": "service_level_8193df42-05d3-4874-be18-2ee72a82210f"
  },
  "labelInput": {
    "labelSize": "FOUR_BY_SIX",
    "labelFileType": "PDF"
  }
}

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"
    },
    "labelCreateWorkflow": [
      {
        "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"
          }
        ]
      }
    ]
  }
}
5

Void labels

In the event that a customer wants to void a label, 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?