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

27 August 2025

The August release of Basil introduces these features to our GA channel:

Payouts to Financial Accounts v2 : You can now create a payout to any v2 Financial Account by specifying its ID.
Third-party tax apps : When using subscriptions in flexible billing mode, you can now use any third-party tax app .

Our public preview channel also includes several updates:

Flexible billing mode is now the default : When you create Subscriptions with this public preview version , the subscriptions default to flexible billing mode . Flexible billing mode changes how those Subscriptions behave at different points in their lifecycle, such as calculating prorations, handling trials and managing usage-based billing.
Accounts v2 improvements : You can now deactivate configurations for v2 Accounts , changing how your user is represented in Stripe. You can apply and remove configurations as you go.
Overcapture with payment line items : You can now include payment line items , which help facilitate reconciliation and improve authorisation rates for payment methods such as Klarna and PayPal, if your integration uses overcapture .

30 July 2025

The July release of Basil introduces these features to our GA channel:

Personalised invoices : You can now personalise the appearance of your post-payment invoices with Invoice Rendering Templates , for different customers, a useful feature for Checkout and Payment Links.
Ad hoc pricing for Payment Links : You can now specify a Price while creating a Payment Link in just one API request.
Billing improvements : Subscription schedules can now have phases with mixed durations . Subscriptions that use the flexible billing mode now support thresholds for usage-based billing and mixed intervals with different recurring prices.

Our public preview channel also includes several updates:

Faster onboarding for Accounts v2 : When using Accounts v2 , you can now onboard users with the new Account Links v2 API, which forwards the user to a Stripe-hosted onboarding experience.
New Connect embedded component : The Instant Payouts promotion shows your connected accounts the available funds to pay out and a call-to-action to initiate a payout.
Smart Disputes : The Disputes API now shows when Smart Disputes can automatically manage disputes for you.
Payment line items support : You can now add payment line items for any payment for multicapture and incremental authorisation .

30 June 2025

This month’s release brings these new additions to our GA channel:

Support for crypto payments : You can now use crypto with the Payment Methods API and customers who pay with crypto can settle as fiat in your Stripe balance .
New billing mode for subscriptions : Opt into a broad set of more flexible subscription behaviours , such as better proration calculation, metered pricing improvements and improved trial support.
Flexible payout schedules : You can now customise payout schedules for Accounts to select multiple days in a week or month.

Our public preview channel also includes these new additions:

Saving Klarna payment methods : By saving these payment methods , you can charge your customer at a later date (either off-session or on-session).
Accounts v2 proof-of-address and capabilities : You can now provide proof-of-address documents and better responses for unsupported capabilities .

28 May 2025

New features in our GA channel include:

Expanded payment method support : We’ve added new capabilities for Pix, Satispay, Naver Pay, WeChat Pay and PayPal and South Korean payment methods across several APIs.
Simulated the related setting reader support : You can now use the Reader API with a simulated the related setting terminal .
New balance types : Balance Transactions now specify a balance type and provide balances for refund and dispute prefunding.
Partial payments on invoices : You can now attach multiple Payment Intents to one Invoice, allowing for partial and multiple payments .

Our public preview channel includes several updates:

Flexible billing mode for Subscriptions : You can migrate individual subscriptions to a flexible mode , which provides fine-tuned calculation and orchestration

30 April 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 behaviour.

31 March 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 reorganised 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 the related setting 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.

Basil releases

Breaking changes Product Category All

Relevant changes only

2025-08-27.basil

Connect and payout enhancements

Adds Payout Details embedded component to the Account Session API Connect Public preview for Payout Details embedded component Connect Adds support for paying out to Financial Accounts v2 Payouts

Billing enhancements

Adds a name field to the customer portal configuration object Billing Adds support for invoice items metadata and period in subscriptions and schedules Billing Adds support for third-party tax on flexible billing mode subscriptions Billing

Payment method enhancements

Adds PayPay settings to the Account object Connect + 1 more Adds a Charge Transaction Id for several payment methods Payments Adds the number of instalments for Alma payments to Charge objects Payments Adds support to include the IOF tax in the amount for Pix payments Checkout + 1 more Adds excluded payment method types to the Payment Intents API Payments

Terminal enhancements

Adds support for simulating card payments on Terminal readers Terminal Adds support for PayNow on Terminal Terminal Adds support for MXN currency in Terminal tipping configuration Terminal Makes CVC optional when presenting a payment method on a simulated reader Terminal

Additional updates

Adds Android APK for Terminal to purpose of file uploads Affects all products Adds support for Dispute Preventions Payments Adds support for custom expiry dates to Issuing virtual cards Issuing

2025-07-30.basil

Checkout enhancements

Enhances Checkout for app-to-web purchases Checkout Adds support for disabling future usage in Checkout sessions Checkout Adds support for Invoice Rendering Templates on Checkout and Payment Links Checkout + 1 more Adds support for the NZ the related setting Direct Debit local payment method in Checkout and Payment Links Checkout + 2 more

Billing enhancements

Adds a duration parameter for schedule phases Billing Adds support for quantity adjustment to the Customer Portal Configuration API Billing Adds helpers to cancel subscriptions for billing periods with mixed intervals Billing Adds support for billing thresholds on flexible billing mode Subscriptions Billing Adds support for mixed intervals on the same subscription Billing

Additional updates

Adds transaction ID to Charges for Cash App Payments Adds support for the America/Coyhaique time zone Affects all products Adds a new value to payment review closed reasons Radar Adds support for ad-hoc products and prices when creating Payment Links Payment Links Adds support for new tipping currencies to the Terminal Configuration object Terminal Adds Connect embedded component for Instant Payouts promotion Connect

2025-06-30.basil

Connect enhancements

Verification Sessions can now collect verification information for a related Person Connect + 1 more Adds the ability to provide proof-of-address documents for connected accounts Connect + 2 more Adds more flexible schedules for monthly and weekly payouts Connect + 1 more

Payment method enhancements

Adds new plan types for Japan instalments Payments Adds support for saving Klarna payment methods Billing + 1 more Adds the related setting as a supported bank when using iDEAL Payments Adds support for crypto payment method Crypto

Additional updates

Adds optional filter by status when listing Financial Accounts Treasury Adds support for collecting card details and confirming Payment Intents to server-driven Terminal integrations Terminal Adds Visa compliance disputes Payments Adds billing mode for more flexible subscriptions behavior Billing

2025-05-28.basil

Enhancements for Balances and Balance Transactions

Adds balance types to the Balance Transactions API Issuing + 3 more Adds refund and dispute prefunding balances to the Balance API Payments

Payment method enhancements

Adds South Korean payment methods to the Payment Method Configurations API Connect Adds account capability for the Pix payment method for US-based sellers Payments Adds option to Checkout Sessions to let customers remove saved payment methods Checkout Adds capture method option to Satispay payments Payments Adds support for setting up future usage of Naver Pay in Checkout Sessions Payments Adds support for WeChat Pay for Setup Intents Payments Adds network decline codes for PayPal refunds Payments

Additional updates

Adds simulated the related setting device type to Reader API Terminal Reintroduces billing thresholds Billing + 1 more Extracts sex and place of birth from government-issued ID documents Identity Adds metadata field on Tax Calculation line items Tax Adds two new Connect embedded components for Disputes Connect Adds forms to Terminal readers to collect user information Terminal Adds support for partial payments on invoices Billing + 1 more

2025-04-30.basil

New country support for Tax Registration

Adds support for tax ID types in ten new countries Tax Tax Registration API now supports twelve new countries Tax

Regulatory enhancements

Adds a demographic information hash to the Persons API Connect + 1 more Adds a minority-owned business designation field to the business profile hash Connect + 1 more

Payment method enhancements

Adds Affirm as a supported payment method for one-off invoices and subscriptions Billing Adds tax ID to Payment Method billing details Payments Adds Pix to payment method configurations Payments Adds capture method option to Billie payments Payments

Events enhancements

Adds context field to event payload Affects all products Adds a new ping event type for testing an event destination Affects all products

Additional updates

Adds a field explaining why refunds are pending Payments Adds registration date to the Accounts API Capital + 1 more Adds wallet options to Checkout Sessions Checkout Adds support for card instalments on Confirmation Token Elements + 1 more

2025-03-31.basil

Breaking changes

Coupons enhancements

Removes support for discount coupons that don’t have a specified end time Billing Removes coupon and promotion code parameters with stackable discounts Billing

Increase Invoice flexibility

Replaces top-level price fields with improved price modelling on Invoice Items and Invoice Line Items Billing + 1 more Replaces top-level tax-related properties with improved tax modelling on Invoices, Invoice Line Items, and Credit Note Line Items Billing + 1 more Adds support for multiple (partial) payments on invoices Billing + 2 more Adds jurisdiction level and taxability reason to manual tax amounts on invoices Invoicing

Billing enhancements

Adds subscription item-level billing periods and removes subscription-level periods Billing Invoicing resources now specify how they were generated Billing + 1 more Adds support for last aggregation formula on meters Billing Adds new webhook event types for Billing Meters Billing Adds new webhook event types for billing credits Billing

Elements with Checkout Session

Adds custom UI mode to Checkout Sessions Checkout Adds the initCheckout method Checkout + 1 more

Deprecations to billing features

Replaces Upcoming Invoice API methods with the Create Preview Invoice API Billing + 1 more Removes legacy usage-based billing Billing + 1 more

Issuing enhancements

Adds reason code for Issuing authorisations created while Stripe is unavailable Issuing HTTP Accept headers for webhooks now specify JSON during Issuing authorisations Issuing Adds expired status for Issuing Authorisations Issuing

Payment enhancements

Updates the Vault and Forward API to return a 402 status code for upstream request timeouts Payments Removes manual capture method for Interac cards Payments + 1 more Payment Methods won’t allow modifying fields for Naver Pay after the object is first created Payments Partially capturing or cancelling payments no longer creates a Refund Payments Adds support for Klarna in the hosted invoice page Billing Adds ability to configure saved payment methods for one-time payments on the hosted invoice page Connect + 1 more Adds support for saving and reusing Naver Pay payment methods Billing + 4 more Adds support for the Billie local payment method Checkout + 5 more Adds support for the Satispay local payment method Checkout + 5 more Makes the client parameter optional for WeChat Pay until confirmation Invoicing Adds support for the New Zealand the related setting Direct Debit local payment method Billing + 6 more

Checkout enhancements

Checkout Session removes shipping details Checkout Checkout Sessions have lower latency and new update semantics Checkout Checkout Session allows shipping option updates Checkout Adds permissions parameter to Checkout Sessions Checkout Adds optional items to Checkout Sessions and Payment Links Checkout + 1 more

Additional updates

Removes total count expansion for list API methods Affects all products Adds new error codes for required verifications Connect Updates the default layout for Payment Element Elements Changes the political exposure property of the Person object from a string to an enum Connect Adds default value to custom fields on Payment Links Payment Links Expanded availability of Account KYC data Connect Adds new error code for failures with the Setup Intents API using mobile wallets Payments + 1 more Adds presentment details for Adaptive Pricing Checkout Adds BalanceTransaction types related to pay with Stripe balance Connect + 1 more Introduces new customer balance transaction types Billing Removes support for the page parameter Affects all products Adds ability to configure WiFi for Terminal readers Terminal