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/v1/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`
`include`	string	Comma-separated related resources to include: `bridge`, `order`


curl -X GET "https://api.orderly-hub.com/api/v1/shipments?status=in_transit&limit=50&include=bridge,order" \
  -H "Authorization: Bearer oh_..."

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/v1/shipments/:id

Retrieve a single shipment by ID.

Requiredshipments:read

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

Supports include query parameter to include related resources: bridge, order.


curl -X GET "https://api.orderly-hub.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000?include=bridge,order" \
  -H "Authorization: Bearer oh_..."

Create Shipment

POST/api/v1/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-hub.com/api/v1/shipments" \
  -H "Authorization: Bearer oh_..." \
  -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/v1/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-hub.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{"status": "delivered"}'

Perform Shipment Action

POST/api/v1/shipments/:id/actions

Execute an action on a shipment such as hold, redirect, redeliver, or add delivery instructions.

Requiredshipments:write

Performs an action on an in-flight shipment. Actions are validated against the shipment’s current status — not all actions are available for every status. An action record is created and the carrier is notified asynchronously.

Action Types and Status Requirements

Action Type	Allowed Statuses	Description
`hold`	`in_transit`, `out_for_delivery`	Place a hold on the shipment at the carrier facility
`redirect`	`in_transit`	Redirect the shipment to a different address
`redeliver`	`exception`	Request redelivery after a failed delivery attempt
`instructions`	`in_transit`, `out_for_delivery`	Add delivery instructions for the driver

Request Body

The request body uses a discriminated union on actionType. Each action type has its own config shape.

Hold

Field	Type	Required	Description
`actionType`	string	Yes	Must be `hold`
`config.reason`	string	Yes	Reason: `customer_request`, `address_issue`, `payment_issue`, `inventory_issue`, `other`
`config.notes`	string	No	Additional notes (max 500 characters)

Redirect

Field	Type	Required	Description
`actionType`	string	Yes	Must be `redirect`
`config.address.street`	string	Yes	New street address
`config.address.city`	string	Yes	New city
`config.address.state`	string	Yes	New state
`config.address.zip`	string	Yes	New ZIP code
`config.address.country`	string	No	New country
`config.notes`	string	No	Additional notes (max 500 characters)

Redeliver

Field	Type	Required	Description
`actionType`	string	Yes	Must be `redeliver`
`config.preferredDate`	string	No	Preferred redelivery date
`config.instructions`	string	No	Redelivery instructions (max 500 characters)

Add Instructions

Field	Type	Required	Description
`actionType`	string	Yes	Must be `instructions`
`config.instructions`	string	Yes	Delivery instructions (max 500 characters)


curl -X POST "https://api.orderly-hub.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "actionType": "hold",
    "config": {
      "reason": "customer_request",
      "notes": "Customer wants to change delivery date"
    }
  }'

Redirect example


curl -X POST "https://api.orderly-hub.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000/actions" \
  -H "Authorization: Bearer oh_..." \
  -H "Content-Type: application/json" \
  -d '{
    "actionType": "redirect",
    "config": {
      "address": {
        "street": "456 Oak Ave",
        "city": "Brooklyn",
        "state": "NY",
        "zip": "11201",
        "country": "US"
      },
      "notes": "Customer moved"
    }
  }'

Response


{
  "actionId": "uuid",
  "status": "pending"
}

Delete Shipment

DELETE/api/v1/shipments/:id

Permanently delete a shipment.

Requiredshipments:write

Permanently deletes a shipment from the organization. This action cannot be undone.


curl -X DELETE "https://api.orderly-hub.com/api/v1/shipments/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer oh_..."

Response


{
  "success": true
}