Shipments

Manage shipments associated with orders. Shipments represent physical packages being sent to customers and include carrier, tracking, and rate information.

List Shipments

GET/api/shipments

List all shipments with filtering and pagination.

Requiredshipments:read

Returns a paginated list of shipments for the current organization.

Query Parameters

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 20, max: 100)
`status`	string	Filter by status: `pending`, `label_created`, `in_transit`, `delivered`, `exception`
`order_id`	string	Filter by associated order ID
`carrier`	string	Filter by carrier code
`sort`	string	Sort field (default: `created_at`)
`order`	string	Sort direction: `asc` or `desc`


curl -X GET "https://api.orderly.dev/api/shipments?status=in_transit&limit=50" \
  -H "Authorization: Bearer ord_sk_..."

Response


{
  "data": [
    {
      "id": "uuid",
      "order_id": "uuid",
      "status": "in_transit",
      "carrier": "fedex",
      "service": "GROUND_HOME_DELIVERY",
      "tracking_number": "794644790132",
      "label_url": "https://...",
      "rate": { "amount": 12.50, "currency": "USD" },
      "ship_date": "2026-01-15",
      "created_at": "2026-01-15T10:30:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 120, "totalPages": 3, "hasMore": true }
}

Get Shipment

GET/api/shipments/:id

Retrieve a single shipment by ID.

Requiredshipments:read

Returns the full shipment object including tracking events, rate details, and label information.


curl -X GET "https://api.orderly.dev/api/shipments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..."

Create Shipment

POST/api/shipments

Create a new shipment and generate a label.

Requiredshipments:write

Creates a new shipment for an order. If a carrier account and service are specified, a shipping label will be generated.

Request Body

Field	Type	Required	Description
`order_id`	string	Yes	The order to ship
`carrier_account_id`	string	Yes	Carrier account to use
`service`	string	Yes	Carrier service code
`parcels`	object[]	Yes	Package dimensions and weight
`ship_from`	object	No	Override origin address
`ship_date`	string	No	Scheduled ship date (ISO 8601)
`metadata`	object	No	Custom key-value metadata


curl -X POST "https://api.orderly.dev/api/shipments" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "carrier_account_id": "660e8400-e29b-41d4-a716-446655440000",
    "service": "GROUND_HOME_DELIVERY",
    "parcels": [{ "length": 12, "width": 8, "height": 6, "weight": 2.5, "unit": "lb" }]
  }'

Update Shipment

PATCH/api/shipments/:id

Update a shipment's editable fields.

Requiredshipments:write

Updates a shipment. Only certain fields can be modified depending on the shipment’s current status. Labels that have already been generated cannot have their carrier or service changed.

Request Body

Field	Type	Description
`status`	string	New status
`tracking_number`	string	Manually set tracking number
`metadata`	object	Custom key-value metadata


curl -X PATCH "https://api.orderly.dev/api/shipments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer ord_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "delivered"}'