Basil

Basil is the second release in our new API versioning model. As the first version in the Basil release, 2025-03-31.basil introduces both breaking changes and new features—subsequent Basil versions will include only additive changes. (Our last release was Acacia: every time we introduce a breaking change version, we move to the next release.)

April 30, 2025

We’ve introduced a number of new features in this latest version, as well as a new public preview channel with early access to new capabilities and upcoming features.

Key updates from our GA channel include:

• Broader tax registration support: Twelve new countries are now supported by the Tax Registration API, enabling businesses to automatically collect tax in those regions.
• Expanded payment method support: We’ve added new capabilities for Affirm, Pix, and Billie across several APIs.
• Test your event destinations: We’ve introduced a new event type so you can ping a webhook endpoint (or other destination type) to test whether it’s ready to receive events from Stripe.

We also have some exciting developments in our public preview channel:

• Global Payouts is now available: Users in the US and UK can send money directly to third parties with a new set of money management APIs.
• Third-party tax provider support: We now support automatic tax calculation with several providers after you install a third-party tax app.
• Retrieve and manage FX rates: The new FX Quote API retrieves our current FX rate and lets you extend that rate for up to a day.
• Scripts support custom business logic: You can now provide scripts to define your own logic for specific API objects and extend Stripe’s behavior.

To get started with these updates, review the changelog and upgrade your API version.

March 31, 2025

This version introduces a significant number of breaking changes. Make sure to review the complete changelog below. Most notably:

• Billing changes: We removed or reorganized a number of capabilities, including legacy usage-based billing and a migration from the Upcoming Invoice API to the Create Preview API. Many of these breaking changes are preparing our APIs for future updates later this year in the Basil release.
• Total counts no longer supported on lists: You can no longer expand the total_count property on lists, because this is no longer a recommended integration pattern.
• Checkout Session changes: Checkout Sessions for subscriptions now postpone creation of subscriptions until after the user completes payment—this both improves latency on all Checkout Session API calls and fixes a common bug where customers couldn’t modify billing details after the first payment attempt.

We’ve also included some new features:

• Payment method improvements: Klarna can now be used on Hosted Invoice Pages, and we’ve introduced support for Naver Pay, Billie, Satispay, and New Zealand’s BECS Direct Debit.
• Build custom UIs for Checkout Sessions: You can now specify a ui_mode of custom to use Elements and Checkout Sessions to design your own checkout page.
• Billing meter improvements: We’ve introduced new webhook events for billing meters and credits, and new aggregation formula (last) to use the final meter event in a time range as the total value for a bill.

To get started with these updates, review the changelog and upgrade your API version.