Shipments — Overview

A Shipment represents a physical package dispatched from a warehouse to a recipient. It is always linked to a DeliveryOrder and tracks the parcel's journey through the carrier network via shipping events.

Shipment Concept

When a DeliveryOrder is accepted by a fulfillment service, the warehouse creates one or more Shipments — one per physical parcel. Each Shipment carries:

A tracking number and optional tracking URL for carrier lookup
A carrier name identifying the logistics provider
An ordered list of shipping events reflecting real-time parcel status
The items packed (SKU + quantity) in details
The addresses associated with the parcel (sender, recipient)

Shipments are created either automatically by a connected warehouse system or manually via the shipmentCreate mutation.

Shipment Lifecycle

Shipment States

The state field reflects the administrative lifecycle of the shipment record itself.

State	Description
`DRAFT`	Shipment record created but not yet active. Tracking may not yet be assigned.
`OPENED`	Shipment is active and tracking events are being ingested.
`COMPLETED`	Terminal state. The parcel has been delivered, returned, or the shipment has expired.

Shipping Events

The lastEvent field (and each entry in events) uses ShippingEventEnum. Events are appended in chronological order and represent carrier-reported milestones.

Event	Description
`NEW`	Shipment label created; carrier has not yet received the parcel.
`INFO_RECEIVED`	Carrier has received shipment information from the sender.
`PENDING`	Parcel is with the sender awaiting carrier pickup.
`IN_TRANSIT`	Parcel is moving through the carrier network.
`OUT_FOR_DELIVERY`	Parcel is on a delivery vehicle en route to the recipient.
`ATTEMPT_FAIL`	A delivery attempt was made but failed (recipient absent, access denied, etc.).
`AVAILABLE_FOR_PICKUP`	Parcel is held at a pickup point or post office.
`DELIVERED`	Parcel successfully delivered to the recipient.
`DELIVERED_TO_SENDER`	Parcel has been returned and delivered back to the sender.
`EXCEPTION`	An unexpected issue occurred (damage, lost, customs hold, etc.).
`RETURNED_TO_SENDER`	Parcel is in transit back to the sender.
`EXPIRED`	Shipment tracking has expired without a final delivery status.

GraphQL Type

graphql

type ShipmentType {
  id: ID!
  reference: String
  tracking: String
  trackingUrl: String
  carrierName: String
  state: ShipmentStateEnum! # DRAFT | OPENED | COMPLETED
  lastEvent: ShippingEventEnum
  addresses: [ShipmentAddressType!]
  details: [ShipmentDetailType!]!
  events: ShipmentEventConnection!
  location: LocationType
  deliveryOrder: DeliveryOrderType
  createdAt: DateTime!
  updatedAt: DateTime!
}

type ShipmentEventType {
  event: ShippingEventEnum!
  date: DateTime!
  message: String
  location: String
  city: String
  country: String
}

Webhook Events

Subscribe to these events to receive real-time shipment notifications:

Event	Description
`shipment/created`	A new shipment has been created.
`shipment/completed`	A shipment has been delivered or returned (terminal state).
`shipment/shipping_event`	A new tracking event has been received from the carrier.

Operations

Operation	Type	Description
shipment	Query	Fetch a single shipment by ID
shipmentCreate	Mutation	Create a shipment manually
shipmentAddEvent	Mutation	Append a tracking event to a shipment
shipmentComplete	Mutation	Mark a shipment as completed

Shipments — Overview ​

Shipment Concept ​

Shipment Lifecycle ​

Shipment States ​

Shipping Events ​

GraphQL Type ​

Webhook Events ​

Operations ​