API upgrades

Your API version controls the API and webhook behavior you see (for example, what parameters you can include in requests, what properties you see in responses, and so on). Your version gets set the first time you make an API request. Each major release, such as Acacia, includes changes that aren’t backward-compatible with previous releases. Upgrading to a new major release can require updates to existing code. Each monthly release includes only backward-compatible changes, and uses the same name as the last major release. You can safely upgrade to a new monthly release without breaking any existing code. To upgrade your API version, follow these steps.

When a Connect platform makes requests on behalf of connected accounts without specifying an API version, Stripe always uses the platform’s API version. Regardless of a connected account’s API version, the platform’s requests on its behalf always return responses matching the API version of the request.

Backward-compatible changes

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 VARCHAR(255) COLLATE utf8_bin column (the COLLATE configuration provides case-sensitivity during lookups).
• Adding new event types.
  • Make sure that your webhook listener gracefully handles unfamiliar event types.

Upgrade your API version

If you’re running an older version of the API, upgrade to the latest version to take advantage of new features and enhanced functionality.

Upgrading your API version affects:

• The API calls you make without a Stripe-Version header: the parameters you can send and the structure of objects returned.
• The structure of objects received with Stripe.js methods such as confirmCardPayment.
• The structure of objects sent to your webhook endpoints (both Account and Connect). However, if an endpoint has an explicit version set, it always uses that version.
• Automated Billing operations performed by Stripe (for example, generating an invoice for a new subscription period) use your account’s default API version. See the API changelog for details about how your default API version impacts these operations.

View your API version and the latest available upgrade in Workbench

See the API version used by recent requests on your account and the latest available upgrade from the Overview tab in Workbench.

When performing an API upgrade, make sure that you specify the API version that you’re integrating against in your code instead of relying on your account’s default API version. To test a newer version for API calls, set the Stripe-Version header (in live or testing environments). Learn how to manage versioning in our server-side SDKs.

Upgrade and test your webhooks

Read our guide on how to handle webhook versioning.

Perform the upgrade

When you’re confident that your code can handle the latest API version, perform the upgrade using Workbench:

1. Open the Overview tab in Workbench.
2. In the API versions section, click Upgrade available, which is visible if a newer API version is available.
3. Review which API version will be assigned to your account, and click Upgrade.

This switches the version used by API calls that don’t have the Stripe-Version header and also switches the version used to render objects sent to your webhooks.

Roll back your API version

For 72 hours after you’ve upgraded your API version, you can safely roll back to the version you were upgrading from in Workbench.

After you’ve rolled back, webhooks that were sent with the new object structure and failed will be retried with the old structure.

Stay informed