Migrate from API v1
v2 is additive. Existing v1 routes remain available while you move checkout traffic deliberately.
Compatibility promise
v1 keeps legacy address fields and order behavior. v2 uses separate /v2 routes and requires a structured address, quote, and idempotency key. Do not rewrite a live v1 checkout in place without a staged test path.
What changes
| Concern | v1 | v2 |
|---|---|---|
| Product lists | Firestore-backed | Versioned cached catalogue with fallback |
| Address | Separate state/LGA/area fields | Required version 2 object |
| Delivery price | Calculated during order | 15-minute quote before order |
| Retry protection | No client idempotency contract | Required idempotency key |
| Order request | Product + address + customer | Quote ID + customer |
Phased rollout
- Move reads
Adopt v2 product endpoints and compare results against v1.
- Build v2 addresses
Update address forms using state, LGA, and town endpoints.
- Add quotes
Create and display delivery pricing before final confirmation.
- Add idempotency
Persist a checkout reference before making order calls.
- Canary orders
Send controlled test traffic, then a small live cohort.
Address migration
Do not blindly relabel legacy addresses as version 2. Ask the customer to confirm a town selected from the current catalogue. Keep the legacy address available only for the v1 fallback until the customer has saved a valid v2 replacement.
Cutover
Track success rate, quote expiry, insufficient funds, duplicate submissions, and delivery-location errors separately by API version. Promote v2 only when these metrics and support workflows are stable.
Rollback
Keep the v1 client path deployable during rollout. A rollback sends new checkouts to v1; it must not retry an uncertain v2 order as a new v1 order without first reconciling the v2 idempotency outcome.