# 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=usd
```
In 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
1. Pin the version on every integration you write. Do not rely on the account default.
2. Use a recent version, not the newest released yesterday. Let a new version bake before adopting it.
3. Read the changelog for the major releases (named releases like Basil). Monthly releases have no breaking changes; majors do.
4. 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.
5. If event payloads look wrong in a webhook handler, check the endpoint's pinned version before debugging your code.