# 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.