The contract held, the clients broke: ten years of Stripe's API

A decade of one company's interface, read entirely from repository artefacts: a specification republished 2,535 times, two spec variants that disagree in both directions, generator and spec pins inside each client release, a changelog tool that gates breaking changes in CI, and seven integrator reports showing where the compatibility machine leaks. A reader can take the decision tree on where to put a version boundary, the four failure classes, and the measurement scripts, and run the same audit on their own published API.

What you get out of it

• A client library that defaults to the newest API version turns every dependency bump into a contract migration, which is the mechanism behind the field that stopped being populated in the basil generation.
• Deprecation can be enforced in code generation rather than at the HTTP boundary: 33 published paths are absent from the generator input while only six operations are formally marked deprecated.
• Holding an API additive-only for nine years tripled the schema count against a 1.8x growth in paths, and the accumulated surface is what forced a second namespace and a scheduled breaking release.
• The generated test double proves shape and never behaviour, and it is locked to the newest version, so no integrator can rehearse the migration the publisher will eventually force.
• In a typed client, the exported symbol table is a second unversioned contract: three of the seven integrator reports here are type-level breaks that the API's own semver gate cannot see.

Scope

Why this, now. Stripe replaced an implicit never-break promise with a published twice-yearly breaking cadence in September 2024, and the 2026 artefacts show the newest consumer of that contract is an agent rather than a developer.

What it does not cover. Everything behind the contract boundary: payment processing, ledgers, data stores, infrastructure and cost, plus any comparison with other payment platforms. There is also no engineering-blog, talk, paper or vendor evidence, because this session's egress policy reached github.com and raw.githubusercontent.com and no other host.