Overview

Stripe has updated the ui_mode parameter for Checkout Sessions with new, more descriptive enum values to better reflect their functionality. The previous generic enum values (hosted, embedded, custom) have been replaced with clearer naming that better describes each integration pattern.

New Enum Values

The updated ui_mode values are:

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

Breaking Change

This is a breaking change. Attempting to set a Checkout Session's ui_mode to the old values (hosted, embedded, or custom) will now fail. Any integration using these deprecated values requires immediate code updates.

Action Items

1. View your current API version in Stripe Workbench
2. Upgrade your SDK to the version corresponding to API version 2026-03-25.dahlia (or update direct API requests with the Stripe-Version header if not using an SDK)
3. Update all Checkout Session creation code to use the new enum values
4. Test your integration thoroughly, including webhook endpoints
5. Perform the upgrade in Workbench (with 72-hour rollback window available)

Stripe provides detailed upgrade guides for all supported languages and SDKs (Ruby, Python, PHP, Java, Node.js, Go, and .NET).