Overview

Stripe has updated the enum values for the ui_mode parameter in Checkout Sessions to use clearer, more descriptive names that better communicate their behavior to developers.

Enum Value Changes

The three ui_mode values have been renamed:

• hosted → hosted_page: Displays Checkout on a hosted page that customers are redirected to
• embedded → embedded_page: Displays Checkout as an embedded page on your website
• custom → elements: Displays Checkout using embedded components on your website

Breaking Change Impact

This is a breaking change. Any attempts to set a Checkout Session's ui_mode to the old enum values (hosted, embedded, or custom) will now fail. Developers must update their integration code to use the new value names.

Required Actions

To upgrade:

1. View your current API version in Workbench
2. Update your SDK to the corresponding version for API version 2026-03-25.dahlia, or add the Stripe-Version header to API requests
3. Upgrade webhook endpoints to use the new API version
4. Test your integration thoroughly against the new version
5. In Workbench, perform the upgrade (you have 72 hours to roll back if needed)

Stripe provides comprehensive upgrade documentation and testing resources to help with the migration.