# Stripe 2026-03-25.dahlia renames Checkout Session ui_mode values

- **Provider:** Stripe
- **Endpoint:** `* /v1/checkout/sessions/**`
- **Effective:** 2026-03-25
- **Severity:** high
- **Change:** enum-added
- **Status:** verified
- **Automatic fix:** `apply-fix`

## What changed

From API version 2026-03-25.dahlia, Checkout Session ui_mode values hosted, embedded and custom are replaced by hosted_page, embedded_page and elements (and form is added). Creating a session with an old value fails, and code that compares the returned ui_mode to the old strings stops matching once the account or SDK is upgraded.

## What to do

When moving to 2026-03-25.dahlia or later, send ui_mode hosted_page instead of hosted, embedded_page instead of embedded and elements instead of custom, and update every comparison of session.ui_mode (including checkout.session webhook handlers) to the new values; handle the new form value too.

## Sources

- Provider notice (2026-03-25): https://docs.stripe.com/changelog/dahlia/2026-03-25/updates-available-checkout-session-ui-modes
- https://docs.stripe.com/api/checkout/sessions/create

## Machine-readable

- Advisory: https://github.com/SriVarshini09/shapi-advisories/blob/main/advisories/stripe-checkout-session-ui-mode-values-renamed.json
- OSV: https://shapi.dev/osv/stripe-checkout-session-ui-mode-values-renamed.json