API versioning and upgrades
Stripe versions the whole API, not individual endpoints. A version string marks a snapshot of response fields and behavior. Your account pins one version, and every request without an override uses it.
Version sources
| Layer | Setting | Scope |
|---|---|---|
| Account | Default API version in the Dashboard | Every request that omits the header |
| Request | Stripe-Version header | One request |
| Client library | Version bundled with the SDK release | Requests sent through that client |
The account pin prevents silent breakage. Stripe can release a new default version, and your integration keeps returning the fields it parsed last year.
Override the version
Send Stripe-Version to test a different snapshot without touching the account default.
curl https://api.stripe.com/v1/payment_intents/pi_3Rsx4dDtWMrPDtgt0mUrePJ9 \
-u "$STRIPE_SECRET_KEY:" \
-H "Stripe-Version: 2024-06-20"
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, {
apiVersion: "2024-06-20",
});
The header accepts a dated version such as 2024-06-20. Some releases append a codename, which you must copy exactly from the Dashboard.
A version override changes request behavior as well as response fields. Read the changelog entry before you adopt a version.
What can change
Stripe separates additive changes from breaking ones.
| Change | Releases in any version | Requires a new version |
|---|---|---|
| --- | --- | --- |
| New optional request parameter | Yes | No |
| New response field | Yes | No |
| New event type for webhooks | Yes | No |
| Renamed field | No | Yes |
| Changed field type | No | Yes |
| Removed field | No | Yes |
| Changed default value | No | Yes |
A client that ignores unknown fields accepts every additive change. A client that validates responses against a closed schema fails on the first new field.
Build a forward-compatible parser
Read the fields you need and ignore the rest. Never fail a response because of an extra key.
function readAmount(intent) {
const amount = intent.amount;
if (typeof amount !== "number") {
throw new Error("amount is missing from the PaymentIntent response");
}
return amount;
}
The check confirms the field you depend on. It leaves the rest of the object alone, so a new amount_details key or a new status value doesn't crash the parser.
Don't branch on the full response structure, such as comparing keys against a fixed list. Stripe adds fields in most releases, and a strict comparison fails on the next one.
Upgrade in test mode
Run this sequence before you move the account pin.
- Open the API changelog and read every entry between your version and the target.
- Note the fields your code reads and the request parameters it sends.
- Send a sample of real requests with the
Stripe-Versionheader set to the target. - Compare the responses against your parser, not against a visual diff alone.
- Run the integration test suite against the target version.
- Deploy the code that handles the old and new response formats, if the change needs it.
- Change the account default in the Dashboard.
- Watch the error rate and the webhook failure rate for one payout cycle.
Test with a restricted key scoped to the resources in the suite. A full secret key in a version test can leave stray objects in the account.
Keep SDK and API versions aligned
An SDK release bundles a default API version. Upgrading the library can move your requests to a newer snapshot even when the account pin hasn't changed.
| Action | Effect on the API version |
|---|---|
| Upgrade the SDK and accept its default | Requests use the version bundled with the release |
Upgrade the SDK and set apiVersion | Requests use the version you name |
| Change the Dashboard default | Affects requests that send no header and set no client version |
Set apiVersion explicitly when you upgrade the library. That keeps the API snapshot fixed while you review the SDK changes on their own.
Handle webhooks across versions
A webhook event records the API version that created it, under api_version. Stripe sends events with the version pinned to the endpoint, not the version pinned to the account.
Read the consequences before you share one handler across both paths.
- Separate pins. An endpoint can deliver events on a different version than your API calls use.
- Field drift. A field you read from an API response may not exist on the event payload.
Read the event's api_version when you log a payload, and validate the fields the handler needs rather than the whole object.
Next steps
- Errors and retries when a version change breaks a call in production.
- Idempotent requests for the retry behavior during an upgrade.
- Stripe API changelog for the entry behind each version.