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.

The current version is 2026-09-30.endive. For information on all API updates, view our API changelog. To upgrade your API version, see API upgrades.

• Starting from stripe-ruby v9, the requests you send using stripe-ruby align with the API version that was current when your version of stripe-ruby was released.
• On stripe-ruby v8 or lower, requests made with stripe-ruby use your Stripe account’s default API version, controlled in Workbench.

You can override the API version in your code in all versions.

To override the API version, assign the version to the Stripe.api_version property, or set it per-request. When overriding it per-request, methods on the returned object reuse the same Stripe version.

Webhook events use the API version that’s set during your webhook’s endpoint creation. Otherwise, they use your Stripe account’s default API version (controlled in Workbench). If you’re on stripe-ruby v9 or later, match your webhook endpoint API version to the version pinned by your stripe-ruby version (Stripe.api_version property).

You can upgrade your API version in Workbench. As a precaution, use API versioning to test a new API version before committing to an upgrade.

Some properties on API resources use a fixed set of possible string values, which are known as enums. Enums can be closed or open:

• Closed: The set of values for the enum is fixed and won’t grow or change over time.
• Open: The set of values for the enum can grow or change over time. Stripe can add new values as a backward-compatible change without requiring an API version upgrade. Each enum’s reference entry indicates whether it is open.

Handling open enums in responses

Don’t assume that the values documented for an open enum are exhaustive. When you read an open enum from an API response, your code should include a safe fallback—such as a default branch in a switch statement—to gracefully handle values your integration doesn’t yet recognize.

Sending enum values in requests

When sending an enum value in a request, use only the values documented for the parameter you’re setting. Even if an enum is open, Stripe validates request values against the set of values that are currently supported.