What Stripe understood about API versioning
Stripe's API design gets praised often, usually for its documentation. The more interesting thing is the versioning, because it reflects a decision about who absorbs the cost of change.
The usual approach
Most APIs version by URL path: /v1/, then /v2/ when a breaking change is needed. Old versions get a deprecation notice and a sunset date. Every integrator who wants to keep working has to do migration work on your schedule.
That cost is invisible to the API provider and very visible to everyone else. Multiply it by thousands of integrations and it is a large amount of work being pushed onto other people.
What Stripe does instead
Each account is pinned to the API version it first integrated against. New accounts get the current version. Existing ones keep receiving responses shaped the way they have always been shaped, and upgrade deliberately when they choose to.
Internally this means maintaining transformation layers that convert current responses back into older formats. Every breaking change adds another. It is genuinely expensive engineering, and it never stops being expensive.
Why it is worth it for them
Stripe's product is embedded in other companies' payment flows — the code path where money moves. A breaking change there is not an inconvenience, it is an incident with revenue attached. Making integrations effectively permanent is a competitive advantage in a market where switching costs are already high and trust is the actual product.
Whether it is worth it for you
Probably not, and that is fine. The transformation layers only pay off at meaningful integrator counts, and if you have twelve API consumers you can email them.
The transferable idea is smaller and more broadly useful: when you make a breaking change, someone pays for it, and you get to decide who. Deciding deliberately, rather than defaulting to "the users do," is the part worth copying. Often the right answer is still to push the cost outward — but it should be a choice rather than an accident.