The Pinned API Version
Stripe versions its API by date, and the platform pins to one rather than following the latest.
Where to find it
Architect Panel → Configuration:
- Site Settings — installation-level settings
- Instance Configuration Fields — per-tenant gateway settings
The pinned version is an application configuration value rather than a screen — it is set alongside the other Stripe settings in the installation’s configuration file.
Why pin at all
Because an unpinned integration changes underneath you. Stripe adds fields, changes defaults and adjusts payloads; pinned, you get the behaviour you tested against, and Stripe maintains that version’s behaviour.
The alternative is an integration that works until the day it does not, for reasons nothing in your own change history explains.
It is an old version, and that is fine
A pinned version being years old is not by itself a problem. Stripe supports old versions for a long time, and the integration was built and tested against that behaviour.
What matters is that it is deliberate, and that somebody knows what it is.
When to move it
- A feature you need exists only in a newer version.
- Stripe has given notice that your version is being retired.
- You are already making substantial changes to the payment integration and can test properly.
Not simply because a newer one exists.
Moving it is a payment change
Which is the highest-consequence category of change you can make. Read Stripe’s changelog across every version between yours and the target, test the full lifecycle against test keys, and have a way back.
The webhook payloads change too
Easy to forget, because webhooks feel separate from API calls. If you have automation reacting to Stripe events and reading fields from the payload, a version change can alter those fields.
Record it
The pinned version, when it was last moved, and what was tested. This is a fact that matters once every few years and is impossible to reconstruct.
Worked example
An installation records its pinned version alongside the date it was set. When Stripe announced a deprecation, the team read the changelog across the gap, moved the pin in a test environment, exercised sign-up, upgrade, cancellation and refund, and checked that the rules reading webhook payloads still found the fields they expected.
Recommendations
- Know your pinned version and when it was set.
- Move it for a reason, not for currency.
- Test the whole lifecycle, not one payment.
- Check automation that reads webhook payloads.