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.)

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.