{"templateId":"markdown","versions":[{"version":"v5","label":"v5 (current)","link":"/migrating-from-v4","default":true,"active":true,"folderId":"8a5edab2"},{"version":"v4","label":"v4","link":"/v4/migrating-from-v4","default":false,"active":false,"folderId":"8a5edab2"},{"version":"v3","label":"v3 (legacy)","link":"/v3/migrating-from-v4","default":false,"active":false,"folderId":"8a5edab2"}],"sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Migrating from v4","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"migrating-from-v4","__idx":0},"children":["Migrating from v4"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"main-changes","__idx":1},"children":["Main changes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Scoped bearer tokens replace the flat v4 API key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Successful responses use a consistent ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ data }"]}," envelope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List responses include ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["meta"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["links"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Errors use a consistent ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{ error: { code, message, details } }"]}," envelope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["List endpoints use page-based pagination with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["page"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["per_page"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Rates, labels, pickups, tracking, LTL, and automation have dedicated"," ","namespaces."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shipment creation supports bulk input with row-level successes and errors."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shipments use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["packages[]"]},"; send one package for a single-package shipment."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Shipment creation accepts ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}," so you can choose regular parcel services"," ","or courier services that support carrier pickup."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mutating endpoints that create or charge accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Product DDP classification has a classify, approve, and manufacturer"," ","verification flow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Automation scopes are consolidated into ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation:read"]}," and"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation:write"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"migration-order","__idx":2},"children":["Migration order"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Create a v5 token with the narrowest scopes your integration needs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update authentication to send ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization: Bearer <token>"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update response parsing for the v5 envelope."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update error handling to branch on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error.code"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Add ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," to any create, purchase, booking, classification, or"," ","credit top-up request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Move workflow-specific calls to the dedicated v5 namespaces."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Test the full flow in sandbox before sending live shipments."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/getting-started"},"children":["Getting Started"]}," for the first request and the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/openapi"},"children":["API Reference"]}," for endpoint-level request and response"," ","schemas."]}]},"headings":[{"value":"Migrating from v4","id":"migrating-from-v4","depth":1},{"value":"Main changes","id":"main-changes","depth":2},{"value":"Migration order","id":"migration-order","depth":2}],"frontmatter":{"seo":{"title":"Migrating from v4"}},"lastModified":"2026-06-11T19:50:44.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/migrating-from-v4","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}