A predictable release cadence for the Stripe API

Stripe is changing how it ships API updates. Historically, the company released new API features as soon as they were production-ready—regardless of whether the change was backward-compatible or not. That approach gave developers immediate access to new functionality, but it also made long-term engineering planning difficult.

The new model introduces a structured release schedule: twice-yearly major releases that may include breaking changes, plus monthly feature releases that are strictly backward-compatible. The first major version under this system is named Acacia.

  • Semiannual major releases (like Acacia) contain breaking changes. Each is named after a plant, reflecting the idea that APIs are growing systems that require careful maintenance.
  • Monthly releases add new features without breaking changes. They retain the name of the most recent major release, signaling that upgrading is safe and requires no changes to existing integrations.

This image is meant to illustrate the new release schedule and versioning format, and does not reflect Stripe’s actual release dates.

  • Each release ships with a corresponding SDK for every supported language, plus updated documentation covering the new features and upgrade paths. Stripe’s SDKs will continue to follow semantic versioning, but each SDK version is now tied to a specific API release, simplifying version management.

A changelog that meets you where you are

The developer changelog at docs.stripe.com/changelog has also been redesigned. The previous version simply listed every update to the Stripe API, without much context for which changes mattered to a given implementation. The new changelog is organized around specific API versions, so developers can more easily identify what applies to them.

Key capabilities of the updated changelog:

  • Clear explanations for each major release, including new features and platform updates
  • Concise summaries of API, SDK, and platform changes, showing how each impacts existing integrations
  • Step-by-step guidance for adopting breaking changes and upgrading to newer API versions
  • Filter and search tools to narrow down relevant updates

Historical information for past API versions has been included as well, making it easier to migrate from older releases to the latest one.

Streamlining upgrades for engineering teams

The combination of a predictable release schedule and a version-aware changelog is meant to help engineering teams adopt API changes faster and with greater confidence. Stripe is also inviting feedback through Stripe Insiders, its community channel for API discussion.