Shipment tracking

Display shipment information, delivery statuses and tracking codes for orders. After an order is confirmed, shipments track the physical fulfillment. Each shipment contains a subset of the order's items and can carry track and trace codes for carrier tracking. An order can have multiple shipments for partial deliveries.

For order statuses and the overall order lifecycle, see Understanding the order lifecycle. For listing and filtering orders, see Order history.

Shipment statuses

The ShipmentStatus enum tracks the delivery state of a shipment.

Status	Description
CREATED	Shipment record created
PROCESSING	Shipment is being prepared
IN_TRANSIT	Picked up by the carrier
OUT_FOR_DELIVERY	Out for final delivery
DELIVERED	Successfully delivered
PARTIALLY_DELIVERED	Some items in the shipment delivered
FAILED_DELIVERY	Delivery attempt failed
CANCELED	Shipment canceled
EXCEPTION	An exception occurred during delivery

Fetching shipments for an order

There are two ways to fetch shipments: nested inside an order query or via the standalone shipments query.

Via the order query

Include the shipments field when querying an order to get all shipments inline.

Query

query OrderWithShipments($orderId: Int!) {
  order(orderId: $orderId) {
    id
    status
    shipments {
      id
      status
      expectedDeliveryAt
      createdAt
      items {
        id
        name
        sku
        quantity
        orderItemId
      }
      trackAndTraces {
        id
        code
        carrierId
        carrier {
          id
          name
          trackAndTraceURL
        }
      }
    }
  }
}

Variables

{
  "orderId": 2075
}

Response

{
  "data": {
    "order": {
      "id": 2075,
      "status": "CONFIRMED",
      "shipments": [
        {
          "id": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "status": "CREATED",
          "expectedDeliveryAt": "2025-12-05T10:00:00.000Z",
          "createdAt": "2025-11-03T14:34:48.828Z",
          "items": [
            {
              "id": "bda8e812-4238-49b4-aafc-6a153e265d59",
              "name": "Douglas Lariks fijn bezaagd ZWART",
              "sku": "157957",
              "quantity": 4,
              "orderItemId": 20151
            },
            {
              "id": "781dd85a-6ba4-4bd0-9399-6d3bb1632b1a",
              "name": "Ventilatie Filterset Fresh Air",
              "sku": "VFS-200",
              "quantity": 2,
              "orderItemId": 20152
            }
          ],
          "trackAndTraces": [
            {
              "id": "2d1860e6-e58c-41b8-b9d7-689b355b0c52",
              "code": "3STEST1234567890",
              "carrierId": 1,
              "carrier": {
                "id": 1,
                "name": "PostNL",
                "trackAndTraceURL": "https://postnl.nl/tracktrace/?B={code}"
              }
            }
          ]
        }
      ]
    }
  }
}

Shipment IDs are UUIDs (strings), not integers. The id argument on the shipment query expects a String!.

Via the shipments query

The standalone shipments query returns a paginated list and supports filtering by order IDs, statuses and date ranges. Use this when you need to list shipments across multiple orders or apply filters.

Query

query ShipmentsByOrder($input: ShipmentSearchInput) {
  shipments(input: $input) {
    items {
      id
      status
      orderId
      expectedDeliveryAt
      createdAt
      items {
        id
        name
        sku
        quantity
        orderItemId
      }
      trackAndTraces {
        id
        code
        carrierId
        carrier {
          id
          name
          trackAndTraceURL
        }
      }
    }
    itemsFound
    page
    pages
    offset
    start
    end
  }
}

Variables

{
  "input": {
    "orderIds": [2075],
    "page": 1,
    "offset": 12
  }
}

Response

{
  "data": {
    "shipments": {
      "items": [
        {
          "id": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "status": "CREATED",
          "orderId": 2075,
          "expectedDeliveryAt": "2025-12-05T10:00:00.000Z",
          "createdAt": "2025-11-03T14:34:48.828Z",
          "items": [
            {
              "id": "bda8e812-4238-49b4-aafc-6a153e265d59",
              "name": "Douglas Lariks fijn bezaagd ZWART",
              "sku": "157957",
              "quantity": 4,
              "orderItemId": 20151
            },
            {
              "id": "781dd85a-6ba4-4bd0-9399-6d3bb1632b1a",
              "name": "Ventilatie Filterset Fresh Air",
              "sku": "VFS-200",
              "quantity": 2,
              "orderItemId": 20152
            }
          ],
          "trackAndTraces": [
            {
              "id": "2d1860e6-e58c-41b8-b9d7-689b355b0c52",
              "code": "3STEST1234567890",
              "carrierId": 1,
              "carrier": {
                "id": 1,
                "name": "PostNL",
                "trackAndTraceURL": "https://postnl.nl/tracktrace/?B={code}"
              }
            }
          ]
        }
      ],
      "itemsFound": 1,
      "page": 1,
      "pages": 1,
      "offset": 12,
      "start": 1,
      "end": 1
    }
  }
}

Fetching a single shipment

Use the shipment query to fetch a specific shipment by its ID. This is useful for a shipment detail page where you want the full shipment data including item details from the original order.

Query

query Shipment($id: String!) {
  shipment(id: $id) {
    id
    status
    orderId
    expectedDeliveryAt
    createdAt
    lastModifiedAt
    items {
      id
      name
      sku
      quantity
      orderItemId
      shipmentId
      orderItem {
        id
        name
        sku
        quantity
        price
        priceNet
        productId
      }
    }
    trackAndTraces {
      id
      code
      carrierId
      shipmentId
      createdAt
      carrier {
        id
        name
        type
        trackAndTraceURL
        logo
      }
    }
  }
}

Variables

{
  "id": "65ad4404-88a6-4f97-9325-34a3a35f1dfc"
}

Response

{
  "data": {
    "shipment": {
      "id": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
      "status": "CREATED",
      "orderId": 2075,
      "expectedDeliveryAt": "2025-12-05T10:00:00.000Z",
      "createdAt": "2025-11-03T14:34:48.828Z",
      "lastModifiedAt": "2025-11-03T14:34:48.828Z",
      "items": [
        {
          "id": "bda8e812-4238-49b4-aafc-6a153e265d59",
          "name": "Douglas Lariks fijn bezaagd ZWART",
          "sku": "157957",
          "quantity": 4,
          "orderItemId": 20151,
          "shipmentId": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "orderItem": {
            "id": 20151,
            "name": "2,1X19,5X300cm Douglas / Lariks fijn bezaagd ZWART (Op=Op)",
            "sku": "157957",
            "quantity": 4,
            "price": 23.31,
            "priceNet": 28.21,
            "productId": 1187
          }
        },
        {
          "id": "781dd85a-6ba4-4bd0-9399-6d3bb1632b1a",
          "name": "Ventilatie Filterset Fresh Air",
          "sku": "VFS-200",
          "quantity": 2,
          "orderItemId": 20152,
          "shipmentId": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "orderItem": {
            "id": 20152,
            "name": "Ventilatie Filterset Fresh Air: 1x ePM10 (M5), 1x Coarse (G4)",
            "sku": "VFS-200",
            "quantity": 2,
            "price": 21.80,
            "priceNet": 26.38,
            "productId": 1139
          }
        }
      ],
      "trackAndTraces": [
        {
          "id": "2d1860e6-e58c-41b8-b9d7-689b355b0c52",
          "code": "3STEST1234567890",
          "carrierId": 1,
          "shipmentId": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "createdAt": "2025-11-03T14:34:48.828Z",
          "carrier": {
            "id": 1,
            "name": "PostNL",
            "type": "DELIVERY",
            "trackAndTraceURL": "https://postnl.nl/tracktrace/?B={code}",
            "logo": null
          }
        }
      ]
    }
  }
}

Shipment fields

Field	Type	Description
id	String!	UUID identifier
orderId	Int!	The order this shipment belongs to
status	ShipmentStatus	Current delivery status
expectedDeliveryAt	DateTime	Expected delivery date and time
createdAt	DateTime!	When the shipment was created
lastModifiedAt	DateTime!	When the shipment was last updated
items	[ShipmentItem!]	Products included in this shipment
trackAndTraces	[TrackAndTrace!]	Tracking codes for this shipment

Shipment items

Each shipment item represents a product from the order that is included in the shipment. The orderItemId links back to the original order line and the orderItem field returns the full order item with pricing and product details.

Field	Type	Description
id	String!	UUID identifier
name	String	Item name (as recorded on the shipment)
sku	String	Product SKU
quantity	Int	Quantity shipped
orderItemId	Int	Reference to the original order item
shipmentId	String!	The shipment this item belongs to
orderItem	OrderItem!	Full order line details

The orderItem field gives you access to the original order line including name, sku, quantity (the ordered quantity), price (unit price excluding tax), priceNet (unit price including tax) and productId. This is useful when the shipment item's name or sku differs from the order line or when you need pricing information.

The quantity on a shipment item can differ from the quantity on the order item. For example, if a customer ordered 10 units and only 6 have shipped, the shipment item quantity is 6 while the order item quantity remains 10.

Track and trace codes

Each shipment can have one or more track and trace codes. The carrier field on each track and trace returns the carrier's details including the trackAndTraceURL for building tracking links.

Field	Type	Description
id	String!	UUID identifier
code	String!	Tracking code from the carrier
carrierId	Int	Carrier identifier
shipmentId	String!	The shipment this code belongs to
carrier	Carrier	Carrier details

Carrier fields

Field	Type	Description
id	Int!	Carrier identifier
name	String!	Carrier name (e.g. PostNL, DHL, DPD)
type	CarrierType!	DELIVERY or PICKUP
trackAndTraceURL	String	URL template for tracking links
logo	String	Carrier logo URL

Building tracking links

When a carrier has a trackAndTraceURL, you can use it to build a tracking link for the customer. The URL typically contains a placeholder for the tracking code. Replace the placeholder with the code value from the track and trace record.

For example, if the carrier's trackAndTraceURL is https://postnl.nl/tracktrace/?B={code} and the tracking code is 3STEST1234567890, the tracking link would be:

https://postnl.nl/tracktrace/?B=3STEST1234567890

The trackAndTraceURL can be null if no URL template has been configured for the carrier. In that case, display the tracking code as plain text so the customer can look it up on the carrier's website manually.

Filtering shipments

The shipments query accepts a ShipmentSearchInput with several filter options.

Field	Type	Description
page	Int!	Page number (default: 1)
offset	Int!	Items per page (default: 12)
orderIds	[Int!]	Filter by one or more order IDs
ids	[String!]	Filter by one or more shipment IDs
statuses	[ShipmentStatus!]	Filter by one or more shipment statuses
createdAt	DateSearchInput	Filter by creation date range
lastModifiedAt	DateSearchInput	Filter by last modified date range
expectedDeliveryAt	DateSearchInput	Filter by expected delivery date range
sortInputs	[ShipmentSortInput!]	Sort order

Example: filter by status

query InTransitShipments($input: ShipmentSearchInput) {
  shipments(input: $input) {
    items {
      id
      status
      orderId
      expectedDeliveryAt
      trackAndTraces {
        code
        carrier {
          name
          trackAndTraceURL
        }
      }
    }
    itemsFound
    page
    pages
  }
}

{
  "input": {
    "statuses": ["IN_TRANSIT", "OUT_FOR_DELIVERY"],
    "page": 1,
    "offset": 20
  }
}

This returns all shipments that are currently in transit or out for delivery across all orders.

Partial deliveries

An order can have multiple shipments when items are delivered in separate batches. Each shipment contains only the items and quantities included in that delivery.

To determine which items from an order have been shipped, compare the shipment items against the order items:

query OrderWithShipmentDetails($orderId: Int!) {
  order(orderId: $orderId) {
    id
    status
    items {
      id
      name
      sku
      quantity
    }
    shipments {
      id
      status
      items {
        orderItemId
        quantity
      }
    }
  }
}

{
  "orderId": 2075
}

{
  "data": {
    "order": {
      "id": 2075,
      "status": "CONFIRMED",
      "items": [
        { "id": 20151, "name": "Douglas Lariks fijn bezaagd ZWART", "sku": "157957", "quantity": 4 },
        { "id": 20152, "name": "Ventilatie Filterset Fresh Air", "sku": "VFS-200", "quantity": 2 },
        { "id": 20153, "name": "Power cord 2x1.50 4.0mtr", "sku": "695123-3", "quantity": 3 },
        { "id": 20154, "name": "Printerstandaard voor ergonomische plaatsing", "sku": "STD-01", "quantity": 3 },
        { "id": 20155, "name": "Accu Cirkelzaag 18V Compact", "sku": "ACZ-18V", "quantity": 4 }
      ],
      "shipments": [
        {
          "id": "65ad4404-88a6-4f97-9325-34a3a35f1dfc",
          "status": "CREATED",
          "items": [
            { "orderItemId": 20151, "quantity": 4 },
            { "orderItemId": 20152, "quantity": 2 }
          ]
        }
      ]
    }
  }
}

In this example, order items 20151 and 20152 have been shipped in full. Order items 20153, 20154 and 20155 have not been shipped yet. You can use this comparison to show customers which items are still pending.

Next steps

• Order history for listing and filtering orders
• Reordering for letting customers reorder from previous orders
• Understanding the order lifecycle for order statuses and transitions