Migrating from API v1 to v2
Prerequisites
- Active v1 API integration - Access to v2 sandbox environment - Test suite for current integration - Feature flag system
This guide covers everything you need to migrate your existing v1 integration to the new v2 API. We recommend a phased approach with dual-running to minimize risk.
Step 1: Audit Your Current Integration
Identify all v1 endpoints your application uses and map them to v2 equivalents. Use our migration mapping table in the API reference.
Step 2: Update Authentication
v2 requires Bearer token authentication. If you are using query parameter auth (?api_key=xxx), migrate to the Authorization header.
Step 3: Update Request Formats
Several request body schemas have changed. Key differences:
- Snake_case field names (v1) → camelCase (v2)
- Pagination: offset/limit → page[after]/page[limit]
- Filters: query params → structured filter syntax
Step 4: Update Response Handling
v2 uses a new envelope format: { "data": {...}, "meta": {...}, "links": {...} }
Step 5: Implement Dual-Running
Run both v1 and v2 in parallel with a feature flag. Compare responses to catch discrepancies.
Step 6: Test in Sandbox
Run your full test suite against the v2 sandbox. The sandbox mirrors production data with 15-minute delay.
Step 7: Gradual Rollout
Switch traffic from v1 to v2 gradually: 10% → 25% → 50% → 100%. Monitor error rates at each stage.
Step 8: Decommission v1
Once fully migrated, remove v1 code paths and update documentation. v1 sunsets December 2026.