How API versioning works

Learn how Stripe versions the API and how a version is chosen for each request.

Stripe versions the API so you can adopt new features on a predictable schedule. Each request, webhook, and automated operation runs against a specific API version, which determines the request parameters you can send and the shape of objects you receive.

The current version of the API is 2026-08-26.dahlia. See the API changelog for a complete record of changes.

You can expect new minor versions of the SDKs with each monthly API version and new major versions of the SDKs with each of the twice-a-year major releases. You might sometimes see a major SDK version update coincide with a monthly API version update when the SDKs need to ship a breaking change.

To upgrade to a new API version, see API upgrades.

API release model

Starting with the 2024-09-30.acacia release, Stripe follows a new API release process where we release new API versions monthly with no breaking changes. Twice a year, we issue a new major release (for example, Basil) that starts with an API version containing breaking changes. You can safely upgrade to any monthly release without updating your code. Upgrading to a new major release can require changes to your existing integration.

What API versions apply to

The API version controls more than the REST response you get back from a single call. It also determines:

The parameters you can send and the objects you receive when you don’t set Stripe-Version .
The structure of objects Stripe.js returns.
The structure of objects Stripe sends to your webhook endpoints .
Automated Billing operations that Stripe performs on your behalf, such as generating an invoice for a new subscription period.

How versions are specified in requests

Stripe selects an API version for every request from one of these sources:

The Stripe-Version header on the request, if you set one.
The API version pinned by your server-side SDK, if you use an SDK.
Your account’s default API version, if you don’t specify a version.

Default API version behavior

Your default API version gets set the first time you make an API request. If your API requests don’t specify an API version with the Stripe-Version header, Stripe uses your account’s default API version, which you can view and upgrade in Workbench.

When you retrieve an event through the API, the structure of the event that Stripe returns is defined by the account’s default API version at the time the event occurred.

Webhook endpoints can also pin their own API version. If an endpoint has an explicit version, Stripe always sends events to that endpoint using that version.

Organization API keys

All API requests made with an organization API key must include the Stripe-Version header to ensure consistency and predictability across your organization’s integrations.

See which versions you use

Open the Overview tab in Workbench.
Review the API versions section to see requests made in the last week.
Your account’s default API version shows the label Default . Any requests made using the latest API version show the label Latest .

Compatible changes and breaking changes

Monthly releases add functionality without requiring code changes. Major releases can include breaking changes, such as renamed fields, removed parameters, or different object shapes. Design your integration to ignore unfamiliar fields and event types.

Stripe considers the following changes to be backward-compatible:

Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses.
Changing the order of properties in existing API responses.
Changing the length or format of opaque strings, such as object IDs, error messages, and other human-readable strings.
This includes adding or removing fixed prefixes (such as ch _ on charge IDs).
Make sure that your integration can handle Stripe-generated object IDs, which can contain up to 255 characters. For example, if you’re using MySQL, store the IDs in a the related setting(255) the related setting utf8 _ bin column (the the related setting configuration provides case-sensitivity during lookups).
Adding new event types.
Make sure that your webhook listener gracefully handles unfamiliar event types.

Version identifiers

API versions use a date-based identifier, such as 2024-09-30.acacia. Twice-yearly major releases also have a name, such as Acacia or Basil. Monthly versions after a major release stay in that named line and don’t introduce breaking changes.