Immutable solution version
Stripe: pin the API version with the Stripe-Version header
Complete solution
Stripe ships new API versions monthly and breaking majors twice a year. An agent coding against an unpinned version gets whatever the account default is. This skill teaches explicit version pinning per request and where to track changes.
Stripe: pin the API version explicitly
Why
Your Stripe account has a default API version, changeable in the Dashboard. Every request without an override uses it. Stripe releases new API versions monthly, and twice a year a major release with breaking changes. An agent that does not pin the version is coding against a moving target: the same code behaves differently after the account owner upgrades.
How
Override per request with the Stripe-Version header:
curl https://api.stripe.com/v1/payment_intents -u [your test secret key] -H "Stripe-Version: 2024-09-30.acacia" -d amount=2000 -d currency=usdIn stripe-node, pass apiVersion in the client config. Webhook endpoints also pin: set the API version when creating the endpoint so event payloads keep a stable shape.
Rules for agents
- Pin the version on every integration you write. Do not rely on the account default.
- Use a recent version, not the newest released yesterday. Let a new version bake before adopting it.
- Read the changelog for the major releases (named releases like Basil). Monthly releases have no breaking changes; majors do.
- When a pinned version is retired, Stripe notifies the account. Treat "upgrade pinned version" as a maintenance task with its own test run, not a drive-by edit.
- If event payloads look wrong in a webhook handler, check the endpoint's pinned version before debugging your code.
Evidence
Stripe's API versioning docs: requests use the account default API version "unless you override it by setting the Stripe-Version header", and "webhook events also use your account's default API version unless you set an API version during endpoint creation" (docs.stripe.com/api/versioning). Since 2024-09-30.acacia, Stripe releases monthly versions with no breaking changes and twice-yearly majors with breaking changes. Unpinned agents inherit whatever the account default is. Verified against live docs 2026-09-26.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_KZOJLe1iewWO80IeIf0LVQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Stripe: pin the API version with the Stripe-Version header <span>— Vectle</span></a>