What Just ChangedAPI changes
API change record

Stripe API versioning: what changes, what breaks, and how to upgrade safely

Reviewed August 18, 2026Evidence confidence: Official Stripe API versioning docsPrimary domain: Payments API / SDK / webhooks
Current decisionDo not treat a Stripe API version change as just a dashboard setting. Record your account default, SDK-pinned version, per-request overrides, and webhook endpoint versions before testing or upgrading production.

What changed?

This page was reframed from one exact Stripe API version into a broader versioning checklist because the risky operational question is usually not just “what is the current version?” It is: which Stripe API version is each part of my integration actually using?

Stripe separates major releases from monthly releases. Major releases can include changes that are not backward-compatible, while monthly releases are described as backward-compatible and use the same release name as the last major release. Stripe also lets integrations send a Stripe-Version header, use SDK-pinned versions, and configure webhook endpoint API versions.

Who is affected?

This matters for teams that maintain Stripe integrations and are changing an account default API version, overriding Stripe-Version per request, upgrading Stripe SDKs, creating webhook endpoints, parsing webhook payloads, or running Connect, refund, dispute, subscription, invoice, checkout, or payment-intent flows.

What can break?

  • Request and response shape mismatch: your code can assume one API shape while Stripe returns another.
  • SDK/version mismatch: newer SDKs can align with the API version current when that SDK version was released, while older integrations may rely on account defaults.
  • Webhook mismatch: webhook event payloads can use a different API version than the request code that created the underlying object.
  • Hidden production drift: one service can pin Stripe-Version while another relies on the account default.

Smallest safe migration

  1. Inventory every version boundary. Record the account default API version, SDK version, per-request Stripe-Version headers, webhook endpoint versions, and any connected-account assumptions.
  2. Separate monthly from major upgrades. Monthly releases should be lower-risk, while major release moves deserve deeper testing.
  3. Test the real flows. Exercise checkout, PaymentIntents, subscriptions, invoices, refunds, disputes, Connect transfers, and webhook consumers that matter to your business.
  4. Upgrade webhooks deliberately. Confirm webhook endpoint versions and parser expectations before changing production.
  5. Deploy during a low-risk window. Monitor Stripe logs, application logs, failed webhooks, and customer-visible checkout behavior after release.

Search phrases this page answers

Stripe API versioning, Stripe-Version header, Stripe webhook API version, Stripe SDK pinned API version, Stripe API upgrade checklist, and Stripe major vs monthly releases.

Official sources

Independent research, not official Stripe support. Verify your own API version, SDK, and webhook endpoint configuration before changing production payments.