DOCS

Create a shipment

Landed Cost•
HomeFor logistics providers Landed Cost Create a shipment

Create a shipment for existing orders

Create shipments and labels with the Zonos API after calculating landed costs and creating orders.

GraphQL

This guide is designed for users who are already integrated with the Zonos API and need to create shipments for existing orders in their system. If you're a shipping platform and want to offer Zonos shipment creation to your customers instead, see our Shipment API guide.

If you're integrated with the Zonos API and approved to ship outside of Dashboard, use the shipmentCreateWorkflow mutation to create shipments and provide tracking information. These mutations also allow you to inform Zonos about domestic shipments to cross-docking facilities.

Note: If you're using a Duty and Tax app with a platform that automatically syncs tracking numbers to Zonos, or if you're shipping directly through Dashboard, these mutations are not required.

Create shipments via API 

After calculating a Landed Cost and creating an order, you can send tracking numbers and other shipment details to Zonos through the API.

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

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
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

1
2
3
4
5
6
{
  "input": {
    "generateLabel": true,
    "orderId": "order_12345678-1234-1234-1234-123456789abc"
  }
}

With Fulfillment Center

1
2
3
4
5
6
7
{
  "input": {
    "generateLabel": true,
    "orderId": "order_12345678-1234-1234-1234-123456789def",
    "fulfillmentCenter": "fulfillment_center_12345"
  }
}

With Custom Tracking

1
2
3
4
5
6
7
{
  "input": {
    "generateLabel": false,
    "orderId": "order_12345678-1234-1234-1234-123456789ghi",
    "trackingNumbers": ["tracking_example_1", "tracking_example_2"]
  }
}

With Service Level

1
2
3
4
5
6
7
{
  "input": {
    "generateLabel": true,
    "orderId": "order_12345678-1234-1234-1234-123456789jkl",
    "serviceLevel": "dhl.express_example"
  }
}

With declared value insurance

1
2
3
4
5
6
7
{
  "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 

To cancel a created label, use the following mutation to void the shipment. Any associated labels will also be voided automatically. Note that once a shipment is voided, it cannot be updated or restored.

Mutation

1
2
3
4
5
6
7
8
9
10
11
12
mutation {
  shipmentStatusUpdate(
    input: {
      shipment: "shipment_12345678-1234-1234-1234-123456789stu"
      status: VOIDED
      note: "Voiding shipment"
    }
  ) {
    id
    status
  }
}

Was this page helpful?

Book a demo

Questions?

Get support
© 2025 Zonoszonos.com
On this page:
  • Create a shipment for existing orders
  • Create shipments via API
  • Void a shipment