Shipments - OrbisCommerce

Create a Shipment

POST /v1/shipments

Creates a new shipment and returns carrier rates. A label is not generated until you call Generate Label.

Request

{
  "carrier": "usps",
  "service": "priority_mail",
  "from": {
    "name": "string",
    "company": "string (optional)",
    "address1": "string",
    "address2": "string (optional)",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string (ISO 3166-1 alpha-2)"
  },
  "to": {
    "name": "string",
    "address1": "string",
    "city": "string",
    "state": "string",
    "zip": "string",
    "country": "string"
  },
  "parcel": {
    "weight": 500,
    "length": 20,
    "width": 15,
    "height": 10
  },
  "reference": "ORDER-12345 (optional)"
}

Response

{
  "id": "shp_01HXYZ1234ABCD",
  "status": "created",
  "carrier": "usps",
  "service": "priority_mail",
  "rate": {
    "amount": "8.50",
    "currency": "USD"
  },
  "from": { },
  "to": { },
  "parcel": { },
  "reference": "ORDER-12345",
  "created_at": "2025-06-01T14:30:00Z"
}

List Shipments

GET /v1/shipments

Returns a paginated list of shipments.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (default: 20, max: 100)
`cursor`	string	Pagination cursor from previous response
`status`	string	Filter: `created`, `label_generated`, `in_transit`, `delivered`, `cancelled`
`carrier`	string	Filter by carrier slug

Response

{
  "data": [ { }, { } ],
  "meta": {
    "total": 142,
    "cursor": "cur_01HXYZ9876EFGH",
    "has_more": true
  }
}

Get a Shipment

GET /v1/shipments/:id

curl https://api.orbiscommerce.com/v1/shipments/shp_01HXYZ1234ABCD \
  -H "Authorization: Bearer YOUR_API_KEY"

Cancel a Shipment

DELETE /v1/shipments/:id

Cancels a shipment. Only shipments with status created or label_generated can be cancelled. If a label has been generated it will be automatically voided.

curl -X DELETE https://api.orbiscommerce.com/v1/shipments/shp_01HXYZ1234ABCD \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "id": "shp_01HXYZ1234ABCD",
  "status": "cancelled",
  "cancelled_at": "2025-06-01T15:00:00Z"
}