> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/reference/session-ui-settings.md). # Session UI Overrides When creating a checkout or tokenization session, include `settings.ui` in `POST /v1/sessions` to change the hosted appearance for that session only. Send only the appearance properties that should differ from the merchant defaults. The optional `settings.ui.languages` field is a separate, per-session language allow-list for the hosted page; it is never a merchant-profile default. | Integration question | Answer | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Where do I send the overrides? | In `settings.ui` in the `POST /v1/sessions` request body. | | When should I use them? | When one session needs a different theme, palette, logo, element visibility, or hosted language policy. | | Which session receives them? | Only the session created by the current request. | | What happens to omitted or null properties? | For appearance properties, Plexo uses the merchant profile default and then the Plexo platform default. `languages` has its own unrestricted behavior below. | | What does the API return? | The session `settings.ui` contains the resolved, immutable `SessionUISettingsSnapshot`. | Do not use request-time overrides to configure future sessions. For reusable merchant defaults, see [Configure hosted UI defaults for a merchant](/rest-api/reference/merchant-ui-settings.md). See the generated [Core API v2 OpenAPI document](https://github.com/plexouy/gitbook-public-docs/tree/main/api-rest/en/openapi/core-api-v2.json). The relevant component schemas are `SessionUISettings` and `SessionUISettingsSnapshot`. ## Request fields Add the `ui` object inside the existing session `settings` object: ```json { "settings": { "ui": { "languages": ["es", "en"], "theme": "auto", "branding": { "logoUrl": "https://merchant.example/assets/checkout-logo.svg", "palette": { "primary": "#1f73df", "secondary": "#eef6ff", "background": "#ffffff", "surface": "#ffffff", "text": "#000000" }, "lightPalette": { "primary": "#0066cc" }, "darkPalette": { "primary": "#cc0000" } }, "elements": { "backButton": "default", "cancelButton": "default", "checkoutDetails": "default", "logo": "default", "titles": "default", "footer": "default" } } } } ``` | Field | Allowed values | Behavior | | ----------------------------------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `settings.ui.languages` | An optional unique array containing only lowercase `en` and `es`, or null | Ordered per-session language allow-list. Omit it, send null, or send `[]` to leave the bundled languages and browser detection unrestricted. | | `settings.ui.theme` | `auto`, `light`, `dark`, or null | Overrides the hosted-session theme. | | `settings.ui.branding.logoUrl` | Absolute HTTPS URL or null | Overrides the merchant profile logo for this session. | | `settings.ui.branding.palette.primary` | `#RRGGBB` or null | Primary action and accent color. | | `settings.ui.branding.palette.secondary` | `#RRGGBB` or null | Secondary accent color. | | `settings.ui.branding.palette.background` | `#RRGGBB` or null | Page background color. | | `settings.ui.branding.palette.surface` | `#RRGGBB` or null | Card and framed-component surface color. | | `settings.ui.branding.palette.text` | `#RRGGBB` or null | Primary text color. | | `settings.ui.branding.lightPalette` | Object with the same five nullable color fields as `palette`, or null | Overrides shared palette values only in light mode. | | `settings.ui.branding.darkPalette` | Object with the same five nullable color fields as `palette`, or null | Overrides shared palette values only in dark mode. | | `settings.ui.elements.backButton` | `default`, `visible`, `hidden`, or null | Controls internal back navigation. | | `settings.ui.elements.cancelButton` | `default`, `visible`, `hidden`, or null | Controls cancellation and return-to-merchant buttons independently of internal navigation. | | `settings.ui.elements.checkoutDetails` | `default`, `visible`, `hidden`, or null | Controls the checkout-details panel. | | `settings.ui.elements.logo` | `default`, `visible`, `hidden`, or null | Controls the logo. | | `settings.ui.elements.titles` | `default`, `visible`, `hidden`, or null | Controls page titles. | | `settings.ui.elements.footer` | `default`, `visible`, `hidden`, or null | Controls the footer. | Both buttons default to `visible`. Omitting `cancelButton` or sending null inherits the merchant preference; `default` resets it to the Plexo default (`visible`). To hide both actions, set both flags to `hidden`. Older sessions without `cancelButton` show the merchant-return action regardless of `backButton`. Existing route and redirect availability rules still apply. Use `lightPalette` or `darkPalette` only for colors that must differ by mode. ## Hosted language policy `settings.ui.languages` applies to both hosted checkout and hosted tokenization sessions created by `POST /v1/sessions`. It does not create a language selector, change future sessions, or persist to the merchant profile or `MerchantUISettings`. Omit `languages`, send null, or send an empty array to keep both bundled languages available and preserve normal browser-language detection. A non-empty array restricts the hosted session to the listed languages. For a restricted array, the hosted page resolves its language in this order: 1. Use the first detected browser language whose normalized base language is allowed. For example, `es-UY` matches `es` and `en-US` matches `en`. 2. If no detected browser language is allowed and `en` is allowed, use `en`. 3. Otherwise, use the first value in the ordered `languages` array. | `settings.ui.languages` | Detected browser languages | Hosted language | | ----------------------- | -------------------------- | --------------- | | `["es", "en"]` | `es-UY`, `en-US` | `es` | | `["es", "en"]` | `fr-FR` | `en` | | `["es"]` | `fr-FR` | `es` | All supplied values must be exactly lowercase `en` or `es` and must be unique. Uppercase, regional, unsupported, empty, or duplicate values return `400` with code `invalid-session-ui-settings`; the validation error is reported at `params.settings.ui.languages`. The session response returns the resolved immutable `SessionUISettingsSnapshot` in `settings.ui`. For a restricted request, its `languages` property contains the ordered value captured for that session, for example: ```json { "settings": { "ui": { "languages": ["es", "en"] } } } ``` For an unrestricted request (omitted, null, or empty `languages`), the snapshot omits the `languages` property rather than returning null or an empty array. The OpenAPI snapshot schema therefore keeps `languages` optional. ## Logo validation If your API client sends `settings.ui.branding.logoUrl`, the value must: * be an absolute HTTPS URI with a non-empty host that is neither `localhost` nor an IP literal; * be between 1 and 2048 characters; * contain no credentials, fragment, or literal/escaped whitespace; and * use a numeric port from 0 through 65535 when a port is present. The merchant logo is profile asset metadata, not a field in `MerchantUISettings`. Use `logoUrl` only to override the logo for the session in the current request. ## Resolution and snapshot For each `POST /v1/sessions` request, Plexo resolves every palette color in this order: 1. Plexo defaults. 2. The merchant's shared `branding.palette`. 3. The merchant's matching `lightPalette` or `darkPalette`. 4. The session's shared `branding.palette`. 5. The session's matching `lightPalette` or `darkPalette`. The session response returns the resulting `SessionUISettingsSnapshot` in `settings.ui`. It contains the resolved theme, element visibility, both light and dark palettes, and derived `onPrimary` and `onSecondary` colors. Changing the merchant profile later does not modify this snapshot. All supplied and resolved colors must use the exact `#RRGGBB` format. Invalid enum values, malformed colors, unsafe logo URLs, or an invalid resolved palette return `400 invalid-session-ui-settings`.