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.

• 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.

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 for the first request and the API Reference for endpoint-level request and response schemas.