Breaking changes
Updates Checkout Session UI mode enum values Breaking changes
What’s new
Updates the ui_mode parameter for Checkout Sessions to use the following clearer, more descriptive enum values:
- hosted _ page : Displays the Checkout Session on a hosted page that customers get redirected to (replaces hosted )
- embedded _ page : Displays the Checkout Session as an embedded page on your website (replaces embedded )
- elements : Displays the Checkout Session using embedded components on your website (replaces custom )
Also adds the form value, which enables you to use the Checkout form UI mode. It provides default Adaptive Pricing support and improved payment method handling.
Why is this a breaking change?
Attempting to set a Checkout Session’s ui_mode to hosted, embedded or custom will fail. If your integration uses any of those values, you must update your code to use the new ui_mode values.
Changes
| Values | Change | Enums |
|---|---|---|
| custom embedded hosted | Removed | Checkout. Session#create Checkout. Session |
| elements embedded_page hosted_page | Added | Checkout. Session#create Checkout. Session |
Upgrade
- View your current API version in Workbench.
- If you use an SDK, upgrade to the corresponding SDK version for this API version.
- If you don’t use an SDK, update your API requests to include Stripe-Version: 2026-03-25. dahlia
- Upgrade the API version used for webhook endpoints .
- Test your integration against the new version.
- If you use Connect, test your Connect integration .
Learn more about Stripe API upgrades.