Every v5 request uses a bearer token:
Authorization: Bearer <token>Tokens are scoped and can optionally expire. Create the first token in the dashboard under Settings -> Integrations -> API. A token with tokens:manage can create and revoke additional v5 tokens through the API.
Successful responses are wrapped in data.
{
"data": {
"id": 12345,
"status": "incomplete"
}
}List endpoints also include meta and links for pagination.
Errors are wrapped in error and include a stable code.
{
"error": {
"code": "validation_failed",
"message": "The given data was invalid.",
"details": {
"packages.0.weight": ["The packages.0.weight field is required."]
}
}
}Branch on error.code, not the message text.
List endpoints use page and per_page. The default per_page is 25 and the maximum is 100.
GET /shipments?page=2&per_page=50| Scope | Purpose |
|---|---|
tokens:manage | Manage API tokens. |
addresses:validate | Validate addresses before creating shipments. |
rates:read | Quote shipping rates. |
shipments:read / shipments:write / shipments:void | Shipment lifecycle. |
labels:create | Purchase and combine labels. |
pickups:write | Schedule and cancel carrier pickups. |
tracking:read / tracking:subscribe | Tracking lookups and notifications. |
batches:read / batches:write / batches:process | Bulk batch flow. |
ltl:read / ltl:write | LTL freight quotes and bookings. |
products:read / products:write | Product catalog updates. |
products:classify / products:approve | DDP classification and approval. |
orders:read / orders:write | Order CRUD. |
boxes:read / boxes:write | Box preset CRUD. |
automation:read / automation:write | Rules, filters, lists, tags, and scheduled automations. |
billing:read | Statements and transactions. |
credits:read / credits:write | Credit balance and top-ups. |
Each operation in the API Reference lists its required scope.