Yesterday I walked through every artifact behind the Stripe profile — the OpenAPI stack, the workflows, the schemas, the conformance ledger, the security surface, the agentic layer. That post was a snapshot of what a strong profile looks like. This week I went back into Stripe with a different intent. I did not want to profile it again; I wanted to use it to interrogate my own process. Stripe is the model API — if I comb through it operation by operation, where does my profiling still fall short, and can whatever I fix on Stripe become the blueprint for fixing it on everyone else?
That reframing is the whole point. A single deep profile is useful. A deep profile that upgrades the process behind every other profile in the network is worth far more.
The gap I found hiding in plain sight
When I read the Stripe profile closely, the omission was almost embarrassing. My profiling captured the contract (OpenAPI, schemas, specs) and the business (plans, rate limits, FinOps) really well. But an entire tier of the API — the part a developer actually wrestles with on day one — existed in the profile only as bare hyperlinks. Stripe’s apis.yml had link-style properties for idempotency, pagination, field expansion, metadata, and testing. It pointed at those doc pages and captured none of what they said.
That is a strange thing to notice on the API that basically invented idempotency keys, cursor pagination, and field expansion as industry conventions. The runtime semantics — the how-it-actually-behaves layer — were the least-captured part of the profile for the provider most famous for getting them right. So that became the work: turn that tier into real, structured, forkable artifacts, with Stripe as the reference implementation.
The new artifacts, drawn from Stripe
Going through Stripe’s surface with a fine-tooth comb produced seven new artifact types, each one now a first-class part of the profile instead of a link:
- Sandbox / test data. The single biggest blind spot across the whole network. Nobody’s profile captured the test cards, test bank accounts, test-mode key prefixes, test clocks, and trigger fixtures a developer needs to exercise an API without moving real money. Stripe’s
4242 4242 4242 4242and its whole decline-simulation surface are now data in the repo. - API conventions. One structured document for the cross-cutting semantics — idempotency, pagination, field expansion, metadata, request IDs, the version header, the error envelope — that OpenAPI does not fully express.
- A structured changelog of Stripe’s dated, release-train versions, as data rather than a link.
- A CLI command catalog — the actual command surface of the Stripe CLI, not just the fact that it exists.
- An embedded-components catalog — Elements, Checkout, Payment Element, the Connect embedded dashboards — the client-side UI layer that is distinct from the server SDKs.
- A data model — a machine-readable entity-relationship graph of the core objects (Customer, PaymentIntent, Charge, Refund, Invoice, Subscription) and how they reference each other.
- A decline-codes catalog — the issuer-level
decline_codetaxonomy that sits underneath a card error, which is a payments-specific thing but exactly the kind of domain knowledge a profile should carry.
While I was in there I also closed two gaps I had left open: a trust center artifact capturing Stripe’s PCI DSS Level 1 and SOC 1/2 posture, and the Connect OAuth scopes that the core key-auth API never exposed in its OpenAPI.
Making the integrations honest
Yesterday’s post described “55 forkable integrations.” I need to be straight about that: they were forkable in ambition, but they sat in a capability format I had since retired. This week I actually made them what I had claimed. Every integration that had a real partner — one that also publishes OpenAPI in the network — was rebuilt as a two-source Arazzo workflow whose every step calls a verified operationId in the real spec on both ends. Stripe to HubSpot, Stripe to Salesforce, Stripe to Avalara, Stripe to Twilio: 44 of them, forkable and executable, not screenshots of a marketplace. The dozen partners with no spec to point at became honest listing-only entries — I would rather record “we cannot build this faithfully yet” than fabricate an integration.
Then I filled the obvious holes in Stripe’s own workflows. The existing set covered payments and billing but skipped Stripe’s other marquee products, so I added native Arazzo workflows for Connect onboarding, Issuing, Identity, Financial Connections, saving a card for future payment, Tax, and Quotes — each one grounded in real operations. And every one of these workflows now has an index, so the collection is browseable instead of being a folder you have to spelunk.
The part that makes it a blueprint
None of this would matter much if it stopped at Stripe. The reason to use the best provider as a template is so the template travels. So the new artifact types went straight into the enrichment contract that drives the whole network, and then I ran the new tier against Stripe’s direct peers — the payments cohort: PayPal, Square, Adyen, Braintree, Plaid, Checkout.com, Razorpay, Wise, GoCardless, and Authorize.Net.
What came back is the best evidence that the blueprint works, because it did not come back uniform. PayPal has a 150-plus code processor-response taxonomy; Square’s test tokens and Adyen’s numbered refusal reasons look nothing like Stripe’s; Plaid and Authorize.Net ship real CLIs; Wise, which is not a card acquirer, correctly has no decline taxonomy at all and said so instead of inventing one. A good process meets each provider where it actually is. The rule I held every one of them to was the same rule I hold myself to on Stripe: capture what the provider really publishes, and skip — never fabricate — what they don’t.
That is what “use Stripe as a blueprint” means in practice. Not copying Stripe’s answers onto other providers, but copying the questions — does it have a sandbox, what are its conventions, where is its changelog, can its integrations be forked — and letting each provider’s real surface fill in the answers. The Stripe profile got deeper this week, but the more durable outcome is that every profile after it starts from a better set of questions. You can browse the readable version at apis.io/stripe and fork the raw artifacts from github.com/api-evangelist/stripe — and then ask how many of these your own API could answer today.
