Track Stripe API Changes: Safe Upgrade Workflow

Yes, you can track Stripe API changes automatically and build a safe upgrade workflow before code breaks, by combining Stripe’s own versioning signals with automated testing and gradual rollouts. The core strategy is to monitor Stripe’s changelog and API version headers, run your integration against new versions in a staging environment, and use feature flags or canary releases to control when production traffic hits the new version.

Why Stripe API Changes Are Different

Stripe releases new API versions roughly every few months, and each version can introduce breaking changes—renamed fields, removed parameters, changed response formats, or new required attributes. Unlike many APIs that let you upgrade at your own pace with long deprecation windows, Stripe ties your account to a specific API version. When you create a Stripe account, it’s pinned to the latest version at that time, and it stays there until you explicitly upgrade. This means your code can keep working indefinitely, but you also miss out on new features and security improvements. The danger comes when you do decide to upgrade: if you jump several versions at once, the cumulative changes can break multiple parts of your integration simultaneously.

How Stripe Versioning Actually Works

Every Stripe API request includes an API-Version header. When you send a request without that header, Stripe uses the default version for your account, which is set in the Dashboard under Developers → API keys → API version. You can also pin a specific version per-request by sending the header explicitly, which is useful for testing or for running different services on different versions. Stripe’s changelog lists every version with its release date and a summary of changes, and each entry links to detailed migration guides. The key fact many developers miss: Stripe does not automatically upgrade your account—you must click “Upgrade” in the Dashboard or change the version in your code. So the risk isn’t that Stripe breaks your code overnight; it’s that you upgrade without proper testing, or you let your version drift so far behind that upgrading becomes a large project.

Automated Tracking: What to Monitor

You can automate the tracking of Stripe API changes in several ways, and the best approach uses multiple signals:

Stripe’s official changelog RSS feed – Stripe publishes an RSS feed at https://stripe.com/blog/changelog.rss. You can subscribe in Slack, Discord, or any feed reader, and get notified the moment a new version is announced.
GitHub release monitoring – If you use a Stripe SDK (like stripe-python or stripe-node), watch the SDK’s GitHub releases. SDKs often add support for new API versions before the changelog is updated, and the release notes mention the API version they target.
API version header in your logs – Log the API-Version header from every Stripe response. Stripe echoes the version it used, so you can verify which version your code is actually hitting.
Webhook event versioning – Stripe webhooks also have a version, and you can see the version in the event payload’s api_version field. If you process webhooks, you need to track this separately from your API calls.

For a more automated approach, you can write a simple script that polls the changelog endpoint (Stripe doesn’t have a public API for the changelog, but you can parse the RSS) and opens a GitHub issue or sends a message to your team when a new version appears. Some teams use tools like Dependabot or Renovate to keep SDKs updated, which indirectly alerts them to API changes because the SDK’s minimum API version bumps.

Building a Safe Upgrade Workflow

Once you know a new version is coming, follow this step-by-step process to upgrade without breaking production:

Read the migration guide – Stripe publishes a migration guide for each version. List every breaking change and map it to your codebase. For example, if the guide says charge.failure_message was renamed to charge.failure_message (a real change in 2019), search your code for that field.
Upgrade your SDK first – Install the latest SDK version in a branch. The SDK is designed to work with multiple API versions, but the latest SDK often has better type definitions and deprecation warnings for old fields.
Test against the new version in staging – Stripe lets you set a different API version per request. In your staging environment, send the Stripe-Version header with the new version (e.g., 2025-04-30) while keeping your account on the old default. Run your full test suite, including webhook handling, and check for any errors or unexpected response shapes.
Use a canary or feature flag – If you have multiple services or microservices, upgrade one service at a time. Set the API version header in that service to the new version, deploy it to a small percentage of traffic, and monitor error rates and key metrics (like successful charges or refunds) for 24–48 hours.
Upgrade your account default – Once all services are tested and deployed with the new version, go to the Dashboard and click “Upgrade” to set the new default. This ensures any requests that don’t specify a version use the new one.
Remove old version headers – After a week or two, remove the explicit version headers from your code so you’re fully on the default. Keep an eye on logs for any missed requests that still use the old version.

Common Pitfalls and How to Avoid Them

Even with a solid workflow, developers hit the same issues repeatedly:

Forgetting webhooks – Webhooks have their own version, and you might upgrade your API calls but leave webhooks on an old version. Stripe sends the event’s api_version field, so you can check it. Always test webhook handling in staging with the new version.
Relying on the default version – If you don’t pin a version in your code, you’re implicitly using your account default. When you upgrade the default, every request changes at once. Pinning per-request gives you control.
Skipping versions – Upgrading from 2020-08-27 to 2025-04-30 means you have to handle every breaking change in between. Stripe’s migration guides are cumulative, but it’s much safer to upgrade incrementally—even if it means doing two or three smaller upgrades over a few weeks.
Not checking response fields – Some changes are subtle: a field might go from a string to an object, or a null value might become an empty array. Use a type checker or schema validator on Stripe responses to catch these.
Assuming SDKs are backward compatible – SDKs are generally backward compatible, but they may use new fields internally. Always test the SDK version you’re using against the API version you’re targeting.

Tools and Techniques for Continuous Monitoring

Beyond the RSS feed, you can set up more robust monitoring:

CI pipeline check – Add a step in your CI that runs a script to fetch the latest Stripe API version from the changelog and compare it to the version your code pins. If they differ, fail the build with a message to review the migration guide.
Contract testing – Use tools like Pact or a simple JSON schema validator to test your Stripe integration against a recorded example of each API version. This catches response shape changes before you even deploy.
Stripe’s test mode – Stripe’s test mode lets you create test data and simulate API calls. You can set a per-request version to the new one in test mode and run your entire test suite against it without affecting production.
Third-party services – Some API monitoring services track Stripe’s changelog and send alerts, but you can achieve the same with a simple cron job that parses the RSS feed and posts to a Slack webhook.

Comparing to Other Payment APIs

Stripe’s approach is stricter than many competitors. For example, PayPal’s REST API uses a versioned path (/v1, /v2) and you can call different versions simultaneously, but they deprecate older versions after a fixed period. Stripe’s per-account versioning means you never get forced off an old version, but you also don’t get automatic updates. This is both a blessing and a curse: it gives you control, but it also means you can fall behind and face a large upgrade later. Some APIs, like Adyen, use a similar account-level versioning, while others, like Braintree, have a single global version that changes over time. The key takeaway is that Stripe’s model rewards proactive, incremental upgrades, and punishes neglect.

Frequently Asked Questions

Can I use two different Stripe API versions in the same project?

Yes, you can set the Stripe-Version header per request, so different parts of your codebase (or different services) can use different versions. This is useful during a gradual upgrade. However, be aware that webhooks are tied to your account default unless you specify a version in the webhook endpoint URL (which Stripe supports). Mixing versions in one codebase can be confusing, so it’s best to limit it to a transition period.

What happens if I never upgrade my Stripe API version?

Your code will keep working indefinitely, because Stripe maintains backward compatibility for old versions. You just won’t get new features, and you might miss out on security improvements or performance optimizations. Also, if you ever need to use a new Stripe feature (like a new payment method), it may only be available in newer API versions. There’s no forced upgrade, but Stripe may eventually stop supporting very old versions—they’ve announced deprecation timelines for versions older than a few years, but as of now, no version has been fully retired.

How do I see which Stripe API version my account is using?

Go to the Stripe Dashboard → Developers → API keys. The “API version” field shows your account’s default version. You can also check the API-Version header in any Stripe response—it echoes the version used for that request. To see which version your code is actually sending, log the request headers or use a network inspector.

Is it safe to upgrade to the latest Stripe API version immediately?

Not usually. You should always read the migration guide and test in staging first. Even if the changes look minor, a renamed field or a changed response type can break your code silently. Stripe’s own documentation recommends testing against the new version with a per-request header before changing your account default. The safest approach is to upgrade your SDK, test in staging, then roll out gradually.

Does Stripe notify you when a new API version is released?

Stripe does not send direct emails or in-app notifications for every API version release. They post to their changelog and often mention it in their blog or release notes. The best way to get notified automatically is to subscribe to the RSS feed or use a service that monitors it. You can also follow Stripe’s official Twitter/X account, but that’s not reliable for timely alerts.

What’s the difference between the API version and the SDK version?

The API version is the version of Stripe’s REST API that your requests use (e.g., 2025-04-30). The SDK version is the version of the library you’re using (e.g., stripe-python 10.0.0). SDKs are designed to work with multiple API versions, but they may have a minimum API version required for certain features. You can use an older SDK with a newer API version, but you might miss out on type definitions or helper methods. It’s best to keep both up to date, but the API version is what determines the actual behavior of your requests.

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →