Get Customer Order Shipments

About

The customerOrderShipments query retrieves all shipments for a specific customer order identified by its order ID. Customers can only access shipments from their own orders — requesting another customer's shipments returns a not found error, preventing enumeration attacks. Use this query to:

• Display shipment tracking information
• Show shipped items and quantities
• Track shipping status and carrier details
• View tracking numbers and shipping numbers
• Display shipment creation timestamps
• Show item-level shipment details

Authentication

This query requires customer authentication:

• Authenticated customers: Provide a valid customer authentication token in the Authorization header. Obtain this token via the Customer Login API.

Authorization: Bearer <accessToken>
X-STOREFRONT-KEY: <storefrontKey>

Arguments

Argument	Type	Required	Description
orderId	Int!	✅ Yes	The numeric order ID for which to retrieve shipments.

Possible Returns

Field	Type	Description
id	ID!	IRI identifier of the shipment.
_id	ID!	Numeric shipment ID.
status	String!	Shipment status: pending, shipped, delivered, cancelled.
trackNumber	String	Carrier tracking number.
carrierTitle	String	Carrier name (e.g. FedEx, UPS, Standard Post).
totalQty	Int!	Total quantity of items in the shipment.
createdAt	DateTime!	Shipment creation timestamp.
items	ShipmentItemConnection	Paginated list of shipment line items.
items.edges.node.id	ID!	IRI identifier of the shipment item.
items.edges.node.name	String!	Product name in the shipment.
items.edges.node.sku	String!	Product SKU.
items.edges.node.qty	Int!	Quantity shipped.
shippingNumber	String	Unique shipping number for the shipment.
totalCount	Int!	Total number of shipments for the order.

Error Handling

Order Not Found

{
  "errors": [
    {
      "message": "Customer order with ID \"999\" not found.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["customerOrderShipments"]
    }
  ]
}

Unauthenticated Request

{
  "errors": [
    {
      "message": "Customer is not logged in.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["customerOrderShipments"]
    }
  ]
}

Invalid Order ID

{
  "errors": [
    {
      "message": "Invalid order ID provided.",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["customerOrderShipments"]
    }
  ]
}

Use Cases

• Display shipment tracking page in customer account
• Show tracking numbers and carrier information
• Display shipped items and quantities
• Track shipment status and delivery progress
• Build shipment history timeline
• Show carrier-specific tracking links

Notes

• Customer isolation: A customer can only view shipments from their own orders. Requesting shipments for another customer's order returns a 404, preventing enumeration attacks.
• Read-only: Only GET operations are available. Shipments cannot be modified through this API.
• Tracking information: Tracking numbers are only available for shipments with carrier information.
• Item-level details: Each shipment item includes SKU and quantity information for order fulfillment tracking.

Related Resources

• Get Customer Order — Query a specific order with shipment summary
• Get All Customer Orders — Query all customer orders
• Get Customer Profile — Query customer profile