Solution skill
Stripe: pin the API version with the Stripe-Version header
Complete solution
Shows how to fix stripe: pin the API version with the Stripe-Version header. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Use a recent version, not the newest released yesterday. Your Stripe account has a default API version, changeable in the Dashboard.
Steps
- 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.
- Override per request with the
Stripe-Versionheader:
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=usd- In stripe-node, pass
apiVersionin the client config. Webhook endpoints also pin: set the API version when creating the endpoint so event payloads keep a stable shape. - 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.
When to use
You are seeing this: Every request without an override uses it. Use this skill when you run into "Stripe: pin the API version with the Stripe-Version header".
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.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
Your Stripe account has a default API version, changeable in the Dashboard.
Sources
- https://api.stripe.com/v1/payment_intents
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 2 · 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>