API versioning: how to change your API without breaking your users
Additive vs breaking change, where the version lives, and how pinning keeps integrations safe - with Stripe's monthly-safe, twice-yearly-major scheme as the worked example.
Every API that has users also has a constraint: you cannot change it freely. Remove a field, rename a parameter or change a default, and some client's integration breaks in production. API versioning is the discipline of changing your API without doing that - and it is cheaper to design before you need it than after.
This guide covers the core strategies, then uses Stripe's documented, production-scale approach (from its official docs, checked 19 November 2026) as the worked example.
The decision that matters: additive vs breaking
Most API change is additive: new endpoints, new optional fields, new enum values a client can ignore. Additive change needs no version at all - well-built clients tolerate unknown fields. A version is only owed when you break the contract: removing or renaming fields, changing types, changing defaults or required parameters, or altering error shapes. Teams that version every release create migration fatigue; teams that never version break strangers. The craft is keeping the contract additive as long as possible and batching the unavoidable breaks.
Where the version lives
- URL path (/v1/charges): the most visible and cache-friendly; standard for major contract generations.
- Header (a version or date header): keeps URLs stable; Stripe uses this pattern, with a dated version string.
- Content negotiation or query params: workable but easier to lose in logs, caches and client code.
The mechanism matters less than the pinning model: which version a request actually gets when the client says nothing.
The Stripe model, as documented
Stripe's docs describe a scheme worth studying because it separates two kinds of change. Since the 2024-09-30.acacia release, Stripe ships monthly API releases containing no breaking changes, and twice-yearly major releases (named, like Basil) that can contain breaking changes. Upgrading across monthly releases is safe without code changes; upgrading across a major release can require changes.
Pinning works on several levels. An account has a default API version. Requests can override it per call with the Stripe-Version header. Webhook endpoints take the version set when the endpoint is created - otherwise the account default. Recent client libraries pin automatically: requests sent through a current library align with the API version that was current when that library version was released, so upgrading the library is how you move versions deliberately. The docs recommend matching a webhook endpoint's version to the one your library pins, so events arrive in the shape your code expects.
Three design lessons generalize. First, default-to-safe: an unspecified request gets the account default, so a new release never silently changes a running integration's behavior. Second, make the break window explicit and rare: monthly safe releases mean users are never forced to migrate on someone else's schedule, only when they choose a major. Third, test before committing: Stripe documents using versioning to test a new version in Workbench before upgrading the account default.
Practical rules for your own API
- Define "breaking" in writing. Publish it; clients plan around it. Removing or renaming anything, type changes, new required fields and changed error semantics are breaking almost everywhere.
- Pin per client, not globally. Each integration should be able to sit on its own version until it chooses to move.
- Never silently re-point a pinned version. A version string must be immutable; change behavior under a new identifier.
- Version webhooks separately from requests. Events your server pushes need the same pinning discipline as calls the client makes - a webhook that changes shape overnight is a breaking change with no client-side opt-in.
- Deprecate with a clock. Announce the retirement date when you introduce the successor; support old major versions for a published window, then remove them on schedule.
Sources
- Stripe API documentation: Versioning (checked 19 November 2026; current version cited there as 2026-10-28.endive): https://stripe.com/docs/api/versioning
Drafted with AI assistance from this source. Stripe's scheme is one vendor's current design; verify any specific behavior against its docs before relying on it.