Evidence ledger
24 sources
Checked 02 Oct 2026
Evidence ledger
One row per claim in The contract held, the clients broke: ten years of Stripe's API: who published it, what grade it carries, when it was written, when the link was last checked, and the quote or figure it rests on. Nothing in the guide is cited from memory, so anything not in this table is not in the guide.
Field guide: The contract held, the clients broke: ten years of Stripe's API, read from its own specification. Research date 2026-10-02. Every row was fetched in this session.
Corpus limit, stated up front. This session's network policy reached github.com and
raw.githubusercontent.com and nothing else. stripe.com, docs.stripe.com, arxiv.org,
usenix.org, infoq.com, web.archive.org, news.ycombinator.com and every other host tested
returned an egress block, and api.github.com is gated to repositories attached to this session.
Stripe's engineering blog, its API documentation, its conference talks and its announcement posts
are therefore absent, and so is every internal system Stripe never published. What remains is the
repository record: specifications, generated client libraries, release metadata, commit history and
the issue threads of integrators. That record is a partial and biased witness. It over-reports the
contract surface Stripe chose to publish and under-reports the implementation behind it, and it
contains no vendor case study, paper or talk at all.
Rows marked measured here are counts this guide computed from files fetched at the stated tag,
with the method given in section 8. Tiers follow the skill's hierarchy: postmortem, source,
adr, casestudy, blog, paper, talk, vendor.
| # | Org | Title | Tier | Published | Checked | URL | Claim taken from it | Supporting quote or figure |
|---|---|---|---|---|---|---|---|---|
| 1 | Stripe | openapi, repository README | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/README.md | The published specification is a build output of a generator Stripe does not publish, and it ships in three parallel channels | "They are instead generated via a custom closed-source generator." Directory table: /latest/ "Latest GA release with v1 and v2 API endpoints", /preview/, /openapi/ "Legacy. v1-only endpoint specifications (still updated every release)" |
| 2 | Stripe | openapi, repository README | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/README.md | There are two contracts: the one published for readers and the expanded one used to generate libraries | "SDK specs (spec3.{json,yaml}) — Contains special annotations, deprecated endpoints, and pre-release features specifically intended to support generating Stripe API libraries." |
| 3 | Stripe | openapi, repository README | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/README.md | An old spec dialect was not migrated, it was parked at a tag | "We used to support OpenAPI 2.0, but have since deprecated its use, and it's no longer receiving updates. It is available on old versions of this repository." (link to tree/v83) |
| 4 | Stripe | openapi, release list | source | 2026-10-01 | 2026-10-02 | https://github.com/stripe/openapi/releases | The contract is republished several times a working day; the highest release is v2535 and nine releases landed on 1 October 2026 | Rows v2527 through v2535, all dated "01 Oct", all carrying API version 2026-09-30.endive |
| 5 | Stripe | openapi, commit history | source | 2017-03-14 to 2026-10-01 | 2026-10-02 | https://github.com/stripe/openapi/commits/master | The specification has been public since March 2017 and its publication rate rose by an order of magnitude after 2022 (measured here) | First commit 2017-03-14; 4,071 commits; commits per year 69 (2017), 204 (2022), 632 (2023), 810 (2024), 1,117 (2025); release tags per year 9 (2020), 116 (2022), 521 (2023), 689 (2024), 723 (2025) |
| 6 | Stripe | openapi, upcoming-changes README | adr | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/openapi/upcoming-changes/README.md | The no-breaking-changes promise was replaced in September 2024 by a scheduled one | "Starting with the 2024-09-30.acacia release, Stripe follows a new API release process where we release new API versions monthly with no breaking changes. Twice a year, we issue a new release (for example, acacia) that starts with an API version that will have breaking changes." |
| 7 | Stripe | openapi, upcoming-changes/rest.md and node.md | adr | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/openapi/upcoming-changes/rest.md | Next month's additive changes, and the next version's name, are published per language before release | "Add support for new value 2026-10-28.endive on enum WebhookEndpoint#create.api_version"; README: "These are for internal use only." |
| 8 | Stripe | openapi, latest/README.md | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/latest/README.md | A second API namespace now ships inside the same specification file as the first | "This directory contains the latest generally available (GA) OpenAPI specifications for Stripe's API, including both v1 and v2 endpoints in a single unified file." |
| 9 | Stripe | spec3.json at tag v83 | source | API 2020-08-27 | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/v83/openapi/spec3.json | The 2020 contract declared 235 paths, 385 operations and 483 schemas (measured here) | info.version "2020-08-27"; 3,763,719 bytes |
| 10 | Stripe | spec3.json at tag v2535 | source | API 2026-09-30.endive | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/v2535/openapi/spec3.json | The 2026 v1 contract declares 431 paths, 612 operations and 1,538 schemas, and marks only six operations deprecated (measured here) | info.version "2026-09-30.endive"; 8,317,513 bytes; deprecated operations: GET on /v1/customers/{customer}/bank_accounts, /v1/customers/{customer}/bank_accounts/{id}, /v1/customers/{customer}/cards, /v1/customers/{customer}/cards/{id}, POST on /v1/issuing/authorizations/{authorization}/approve and /decline |
| 11 | Stripe | spec3.sdk.json at tag v2535 | source | API 2026-09-30.endive | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/v2535/openapi/spec3.sdk.json | Thirty-three published paths are excluded from the generator's input while 285 extra schemas are included (measured here) | SDK spec: 398 paths, 1,823 schemas. Absent from it: /v1/customers/{customer}/cards, /v1/customers/{customer}/bank_accounts, /v1/customers/{customer}/subscriptions, /v1/balance/history, /v1/linked_accounts, /v1/charges/{charge}/refund and 27 more |
| 12 | Stripe | latest/openapi.spec3.json | source | API 2026-09-30.endive | 2026-10-02 | https://raw.githubusercontent.com/stripe/openapi/master/latest/openapi.spec3.json | The v2 namespace is small and holds the rewritten account, event and metering domains (measured here) | 454 paths total: 431 under /v1, 23 under /v2, including /v2/core/accounts, /v2/core/events, /v2/core/event_destinations, /v2/billing/meter_events, /v2/commerce/product_catalog/imports |
| 13 | Stripe | stripe-node CHANGELOG | source | 2026-09-30 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/CHANGELOG.md | The client library's breaking-release cadence went from roughly annual to roughly quarterly (measured here) | 23 majors. Eight to 2020-01-09, median gap 365 days. Fifteen from 2022-05-09 to 2026-09-30, median gap 127 days. 218 occurrences of the breaking-change marker |
| 14 | Stripe | stripe-node CHANGELOG, 23.0.0 | source | 2026-09-30 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/CHANGELOG.md | A library major is the vehicle for both API-generation advance and type-level corrections | "This release changes the pinned API version to 2026-09-30.endive." and "Remove the V1-only object, has_more, and url fields from Stripe.V2List<T>. These fields were never populated and were added only to maintain type compatibility when correcting the V2 list response type in a minor release." |
| 15 | Stripe | stripe-node CHANGELOG, 23.0.0 | source | 2026-09-30 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/CHANGELOG.md | By 2026 the library distinguishes human from machine callers in its own output | "Set the STRIPE_SUPPRESS_NOTICES environment variable to true to suppress Stripe notices in test and sandbox environments when not running under a detected AI agent. Notices remain enabled by default and continue to be shown to AI agents." |
| 16 | Stripe | stripe-node, OPENAPI_VERSION and CODEGEN_VERSION | source | 2022-05-23 and 2026-01-02 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/OPENAPI_VERSION | Each client release records the spec release and generator revision that produced it | File contents: v2526 and 588801ef34f7b5f7d6a784d3354f5f93d2a26ffb. First commits: "Codegen for openapi v146 (#1430)", 2022-05-23; "Copy API_VERSION to CODEGEN_VERSION (#2529)", 2026-01-02 |
| 17 | Stripe | stripe-node, .claude/CLAUDE.md | adr | 2026-02-27 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/.claude/CLAUDE.md | The generated/handwritten boundary is now written as a rule for coding agents | "Files containing File generated from our OpenAPI spec at the top are generated; do not edit... If something in a generated file/range needs to be updated, add a summary of the change to your report but don't attempt to edit it directly." Also: "Multi-platform: exports for Node.js, browser, Deno, Bun, workers" |
| 18 | Stripe | stripe-node README, configuration table | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/README.md | The default behaviour ties the API version to the library version | apiVersion default null: "Stripe API version to be used. If not set, stripe-node will use the latest version at the time of release." |
| 19 | Stripe | stripe-node README, preview features | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-node/master/README.md | The version header became a per-feature negotiation channel, and release phases ship as separate package channels | "use the apiVersion property of config object to set it: apiVersion: '2022-08-01; feature_beta=v3'"; private previews are "versions of this package that have the -alpha.X suffix like 18.6.0-alpha.1" |
| 20 | Stripe | hark, repository README | adr | 2026-09-11 | 2026-10-02 | https://raw.githubusercontent.com/stripe/hark/master/README.md | Breaking-change classification is an artefact in the pull request and a gate in CI | "Each user-facing PR needs a corresponding .change.md file"; hark inspect emits {"path":...,"semver_level":"major|minor|patch"}; "CI can gate a workflow on explicitly selected breaking changes"; "it doesn't accept external contributions and has no public issue tracker" |
| 21 | Stripe | stripe-mock, repository README | adr | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-mock/master/README.md | The generated test double checks shape, not behaviour, and only for the newest version | "stripe-mock does not attempt to reproduce the behavior of the real Stripe API at all"; "It's locked to the latest version of Stripe's API and doesn't support old versions"; "it is powered by the Stripe OpenAPI specification" |
| 22 | operator report | stripe-node issue 2369 | postmortem | 2025-07-10 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/2369 | Advancing the pinned API version changed expansion behaviour in production | "with Subscription object payment intent within latest invoice is not longer populated"; reporter on 18.3.0 with API version 2025-06-30.basil: latest_invoice.payment_intent returns null, while "the identical code works correctly with an older API version (2023-10-16)" |
| 23 | operator report | stripe-python issue 1432 | postmortem | 2024-12-12 | 2026-10-02 | https://github.com/stripe/stripe-python/issues/1432 | The same class of break appears in other languages of the fleet | "Backwards compatibility broken from stripe v7 -> v8 transition"; "StripeError -> http_body becomes None instead of valid dictionary"; "Before v8 both http_body and json_body contain identical data" |
| 24 | operator report | stripe-node issue 2658 | postmortem | 2026-04-04 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/2658 | The type surface is a second contract, and it is versioned less carefully than the first | "v22 and specifically #2619 remove the export for SessionCreateParams. This was no documented and resulted in breaking existing imports." |
| 25 | operator report | stripe-node issue 2661 | postmortem | 2026-04-06 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/2661 | A client can typecheck and still fail at runtime after a major | instanceof Stripe.ErrorType.StripeError "passes type check but throws at runtime" on v22.0.0; labelled bug and future, assigned, unresolved when checked |
| 26 | operator report | stripe-node issue 1593 | postmortem | 2022-10-29 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/1593 | The runtime the client runs in moved, and the client had to be re-shaped to follow | "Unusable in Cloudflare workers due to use of node specific APIs/packages"; Buffer in webhook verification, crypto required early, http/https imports not tree-shaken; "This seems to be a broad regression, given that Cloudflare workers is supposed to be supported" |
| 27 | operator report | stripe-node issue 2211 | postmortem | 2024-10-21 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/2211 | The client's own HTTP layer decides whether integrators can test against it | "Default Node httpClient configuration does not get mocked by MSW nor upcoming Nock version"; nock "is no longer able to intercept requests from this library when using the default Node.js httpClient"; open two years, closed 2026-10-01 |
| 28 | operator report | stripe-node issue 2458 | postmortem | 2025-10-06 | 2026-10-02 | https://github.com/stripe/stripe-node/issues/2458 | A money-affecting regression report can sit without a published root cause | "Invalid amount with 19.1.0 when creating a charge"; same call succeeded on 18.4.0, API version 2024-06-20; no maintainer root cause in the thread when checked |
| 29 | Stripe | stripe-go go.mod | source | current | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-go/master/go.mod | In Go the version boundary is in the import path, so every major is a code change at the call site | module github.com/stripe/stripe-go/v87 |
| 30 | Stripe | server SDK changelogs, seven languages | source | 2026-09-30 | 2026-10-02 | https://raw.githubusercontent.com/stripe/stripe-ruby/master/CHANGELOG.md | The whole client fleet releases its majors on the API generation date (measured here) | Majors dated 2026-09-30: node 23.0.0, go v87, ruby 20.0.0, python 16.0.0, php 22.0.0, java 34.0.0, dotnet 53.0.0. Majors since 2022: 14 or 15 in every language |
| 31 | Stripe | veneur, archive banner and README | source | archived 2025-04-25 | 2026-10-02 | https://github.com/stripe/veneur | Generic platform software was dropped, and the README outlived the project | Banner: "This repository was archived by the owner on Apr 25, 2025. It is now read-only." README still states it "is currently handling all metrics for Stripe and is considered production ready. It is under active development and maintenance!" Last commit 2023-02-27; 1.7k stars |
| 32 | Stripe | goforit, README and commit history | source | 2017-03-01 to 2023-08-01 | 2026-10-02 | https://raw.githubusercontent.com/stripe/goforit/master/README.md | The feature-flag client was retired with a notice rather than replaced in public | "This project is deprecated and is no longer being actively maintained."; final commit "Add deprecation notices (#55)", 2023-08-01 |
| 33 | Stripe | smokescreen, README and commit history | source | 2013-09-17 to 2026-10-01 | 2026-10-02 | https://raw.githubusercontent.com/stripe/smokescreen/master/README.md | What is specific to a regulated payments business was maintained for thirteen years | "Smokescreen also allows us to centralize egress from Stripe, allowing us to give financial partners stable egress IP addresses"; "resolves each domain name that is requested, and ensures that it is a publicly routable IP address"; 745 commits, latest 2026-10-01 |
| 34 | Stripe | skycfg, README and commit history | source | 2018-10-05 to 2026-08-14 | 2026-10-02 | https://raw.githubusercontent.com/stripe/skycfg/master/README.md | Configuration was treated as a typed program, and the repository names the platform it configured | "It was developed by Stripe to simplify configuration of Kubernetes services, Envoy routes, Terraform resources, and other complex configuration data."; 121 commits in eight years |
| 35 | Sorbet (founded at Stripe) | sorbet, README | source | 2017-10-03 to 2026-10-01 | 2026-10-02 | https://raw.githubusercontent.com/sorbet/sorbet/master/README.md | The monolith behind the API is a Ruby codebase large enough to need its own type checker, tested against the monolith by name | "Testing Sorbet against pay-server"; design principle 5, "Scales On all axes: execution speed, number of collaborators, lines of code, codebase age."; 13,524 commits |
| 36 | Stripe | ai, repository README | source | 2024-11-13 to 2026-10-02 | 2026-10-02 | https://raw.githubusercontent.com/stripe/ai/master/README.md | The newest client surface is built for agents, not for developers reading documentation | "Stripe hosts a remote MCP server at https://mcp.stripe.com"; @stripe/token-meter "for integrating Stripe's billing infrastructure with native SDKs from OpenAI, Anthropic, and Google Gemini"; claude plugin install stripe@claude-plugins-official |
| 37 | Stripe | link-cli, repository README | source | 2026-04-23 to 2026-10-01 | 2026-10-02 | https://raw.githubusercontent.com/stripe/link-cli/master/README.md | A payment credential is now issued to an agent, under a protocol separate from the REST API | "Link CLI lets agents get secure, one-time-use payment credentials from a Link wallet to complete purchases on your behalf"; credential types include "A Shared Payment Token (SPT) for use when the seller accepts programmatic payments through Machine Payment Protocols" |
| 38 | Stripe | mpp-rb, repository README | source | 2026-04-22 to 2026-10-01 | 2026-10-02 | https://raw.githubusercontent.com/stripe/mpp-rb/master/README.md | The agent payment path ships as its own protocol SDK rather than as more of the v1 API | "Ruby SDK for the Machine Payments Protocol" |
| 39 | Stripe | organisation repository listing | source | 2026-10-02 | 2026-10-02 | https://github.com/orgs/stripe/repositories?sort=updated&type=all | The published estate is dominated by client libraries and contract tooling | "100 repositories"; first page is the seven server SDKs, the mobile and React SDKs, openapi, hark, stripe-mock, stripe-cli, ai, link-cli, mpp-rb, smokescreen |
| 40 | Stripe | einhorn, commit history | source | 2012-05-17 to 2026-08-13 | 2026-10-02 | https://github.com/stripe/einhorn/commits/master | A 2012 process manager is still receiving fixes, largely from outside Stripe | 339 commits; recent commits 2026-07-14 and 2026-08-13 merged from an external contributor's branches |
What the corpus cannot tell you
- Traffic. Nothing here says how many live integrations sit on which API version, how much
traffic the 33 ungenerated paths still carry, or what share of callers pin
apiVersionexplicitly. That distribution is the whole risk calculation for a deprecation, and it is private. - Behaviour. The specification describes shapes. It cannot express that
latest_invoice.payment_intentstopped being populated, which is exactly the break integrators reported (row 22). - Cost. No figure in this corpus prices the generator, the seven-language fleet or the migration work pushed onto integrators.
- Reasons, mostly.
upcoming-changes/README.md(row 6) is the only place in the corpus where Stripe states a contract policy in its own words. Everything else about motive in this guide is reconstruction from artefacts, and is marked as such.
Addendum, added during the final read
| # | Org | Title | Tier | Published | Checked | URL | Claim taken from it | Supporting quote or figure |
|---|---|---|---|---|---|---|---|---|
| 41 | operator report | stripe-python issue 1779 | postmortem | 2026-03-29 | 2026-10-02 | https://github.com/stripe/stripe-python/issues/1779 | A generated client's hand-written serialisation broke printing of response objects in a major | "str and repr no longer work on StripeObjects with v15"; calling str() or repr() on a Subscription fails with "*** when serializing dict item 'items'"; opened 29 March 2026, closed |