# Migrating from v4

V5 is additive: v4 remains live, and existing v4 integrations do not need to
change immediately. Use this checklist when upgrading an integration or
building new v5-only functionality.

## Main changes

- Scoped bearer tokens replace the flat v4 API key.
- Successful responses use a consistent `{ data }` envelope.
- List responses include `data`, `meta`, and `links`.
- Errors use a consistent `{ error: { code, message, details } }` envelope.
- List endpoints use page-based pagination with `page` and `per_page`.
- Rates, labels, pickups, tracking, LTL, and automation have dedicated
namespaces.
- Shipment creation supports bulk input with row-level successes and errors.
- Shipments use `packages[]`; send one package for a single-package shipment.
- Shipment creation accepts `type` so you can choose regular parcel services
or courier services that support carrier pickup.
- Mutating endpoints that create or charge accept `Idempotency-Key`.
- Product DDP classification has a classify, approve, and manufacturer
verification flow.
- Automation scopes are consolidated into `automation:read` and
`automation:write`.


## Migration order

1. Create a v5 token with the narrowest scopes your integration needs.
2. Update authentication to send `Authorization: Bearer <token>`.
3. Update response parsing for the v5 envelope.
4. Update error handling to branch on `error.code`.
5. Add `Idempotency-Key` to any create, purchase, booking, classification, or
credit top-up request.
6. Move workflow-specific calls to the dedicated v5 namespaces.
7. Test the full flow in sandbox before sending live shipments.


See [Getting Started](/getting-started) for the first request and the
[API Reference](/openapi) for endpoint-level request and response
schemas.