Stripe API versions: pin it, test upgrades in a sandbox, read the Breaking column

TL;DR

Set the version explicitly on every integration: the Stripe-Version header on raw HTTP calls, or the apiVersion option in stripe-node / stripe-python. Stripe's versioning is a contract: your pinned version never changes behavior under you. Run your test-clock scenarios against the new version before promoting.

When to use

You are seeing this: Never rely on the account default. Use this skill when you run into "Stripe API versions: pin it, test upgrades in a sandbox, read the Breaking column".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Stripe API version discipline

Stripe's versioning is a contract: your pinned version never changes behavior under you. Every "Stripe broke my integration" story is really "something upgraded the version without reading the changelog." Agents are prolific authors of that story.

Pin the version

1. Set the version explicitly on every integration: the Stripe-Version header on raw HTTP calls, or the apiVersion option in stripe-node / stripe-python. Never rely on the account default.
2. Record the pinned version in the repo (config file, not tribal knowledge) so the next agent knows what the code was written against.
3. When writing new code, pin the current stable line (Dahlia as of this writing), not whatever version the last project used.

Upgrade on purpose

1. Upgrades are opt-in: change the pinned version in a test-mode sandbox, never in production first.
2. Read the changelog filtered to the Breaking column for every version between your pin and the target. The Dahlia line alone has dozens of breaking entries; most will not affect you, but the ones that do are exactly the removed-parameter and renamed-field kind.
3. Run your test-clock scenarios against the new version before promoting. Billing behavior changes hide in version bumps.
4. Preview versions (for example 2026-03-25.preview) gate preview features like the Trial Offer API. Do not pin production to a preview version; use it in a sandbox to evaluate.

The agent trap

Copying a Stripe-Version header from an old project or a tutorial pins you to an old behavior set, and then the code you write from current docs mismatches the old version. Pin deliberately, per project, and write the version down.

Stripe's versioning docs describe pinning via the Stripe-Version header and SDK apiVersion, opt-in upgrades, and preview versions gating preview features. The Dahlia changelog demonstrates the breaking-change density of a version line. Verified against live docs 2026-09-26.