> 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/merchant-ui-settings.md).

# Merchant UI Defaults

Use the merchant UI settings endpoints when your API client needs the same hosted appearance for new checkout and tokenization sessions, including checkouts created through Payment Links and Quick Pay. Configure these defaults once on the merchant profile instead of repeating them in every session request.

| Integration question               | Answer                                                                                           |
| ---------------------------------- | ------------------------------------------------------------------------------------------------ |
| Where do I configure the defaults? | Use `GET`, `PUT`, and `DELETE /v1/Merchants/{merchantId}/profile/ui-settings`.                   |
| When should I use them?            | When new sessions for the merchant should share the same theme, palette, and element visibility. |
| Which sessions receive them?       | Sessions created after the merchant profile is updated.                                          |
| What does an update not change?    | Sessions that already exist and their UI snapshots.                                              |

**Authentication:** Basic Auth or Bearer Token is required.

**Authorization:** `{merchantId}` must belong to the authenticated client. A missing merchant and a merchant owned by another client both return `404 merchant-not-found`, so the endpoint does not disclose another client's resources.

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 request and response schema is `MerchantUISettings`. To change the appearance of only one session, send `settings.ui` in `POST /v1/sessions`; see [Override hosted UI settings for a session](/rest-api/reference/session-ui-settings.md).

## Operations

| Operation                                               | Behavior                                    | OpenAPI reference                                             |
| ------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------- |
| `GET /v1/Merchants/{merchantId}/profile/ui-settings`    | Read the stored merchant defaults.          | `paths./v1/Merchants/{merchantId}/profile/ui-settings.get`    |
| `PUT /v1/Merchants/{merchantId}/profile/ui-settings`    | Fully replace the stored merchant defaults. | `paths./v1/Merchants/{merchantId}/profile/ui-settings.put`    |
| `DELETE /v1/Merchants/{merchantId}/profile/ui-settings` | Clear the stored defaults.                  | `paths./v1/Merchants/{merchantId}/profile/ui-settings.delete` |

All three operations require the integer `merchantId` path parameter.

## Request model

`PUT` requires a non-null JSON `MerchantUISettings` body. All properties inside the object are optional, but the operation uses replacement semantics rather than merge semantics.

```json
{
  "theme": "auto",
  "branding": {
    "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"
  }
}
```

### Fields and enums

| Field                         | Type                                    | Allowed values and meaning                                                                 |
| ----------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------ |
| `theme`                       | string or null                          | `auto`, `light`, or `dark`.                                                                |
| `branding.palette.primary`    | string or null                          | Primary action/accent in exact `#RRGGBB` form.                                             |
| `branding.palette.secondary`  | string or null                          | Secondary accent in exact `#RRGGBB` form.                                                  |
| `branding.palette.background` | string or null                          | Page background in exact `#RRGGBB` form.                                                   |
| `branding.palette.surface`    | string or null                          | Card/frame surface in exact `#RRGGBB` form.                                                |
| `branding.palette.text`       | string or null                          | Main text color in exact `#RRGGBB` form.                                                   |
| `branding.lightPalette`       | object or null                          | The same five nullable color fields, applied only to light mode.                           |
| `branding.darkPalette`        | object or null                          | The same five nullable color fields, applied only to dark mode.                            |
| `elements.backButton`         | `default`, `visible`, `hidden`, or null | Controls internal back navigation.                                                         |
| `elements.cancelButton`       | `default`, `visible`, `hidden`, or null | Controls cancellation and return-to-merchant buttons independently of internal navigation. |
| `elements.checkoutDetails`    | string or null                          | `default`, `visible`, or `hidden`.                                                         |
| `elements.logo`               | string or null                          | `default`, `visible`, or `hidden`.                                                         |
| `elements.titles`             | string or null                          | `default`, `visible`, or `hidden`.                                                         |
| `elements.footer`             | string or null                          | `default`, `visible`, or `hidden`.                                                         |

Unknown members are rejected. Retired flat fields such as `default_dark`, `autoDarkTheme`, `hideElements`, or a flat `primary` are not aliases and return HTTP `400`.

The existing `branding.palette` field remains supported and applies each supplied color to both modes. For a color in `lightPalette` or `darkPalette`, the mode-specific value takes precedence over the shared value.

### Merchant defaults and validation

When your API client omits a property or sends null, Plexo uses its platform default for that property. The resulting merchant settings apply only when Plexo creates future sessions.

Within the merchant defaults, Plexo resolves each color from the platform default, then `branding.palette`, then the matching `lightPalette` or `darkPalette`. Per-session shared and mode-specific values take precedence when a session is created.

| Value         | Light default | Dark default |
| ------------- | ------------- | ------------ |
| `theme`       | `auto`        | `auto`       |
| `primary`     | `#1f73df`     | `#1f73df`    |
| `secondary`   | `#eef6ff`     | `#173f73`    |
| `background`  | `#ffffff`     | `#242424`    |
| `surface`     | `#ffffff`     | `#2e2e2e`    |
| `text`        | `#000000`     | `#C9C9C9`    |
| Every element | `visible`     | `visible`    |

`PUT` validates both effective palettes after applying Plexo defaults and rejects invalid settings without changing the existing profile.

### Merchant logo

Do not send `logoUrl` in `MerchantUISettings`. The merchant logo is managed as profile asset metadata. To override the logo for one session, send `settings.ui.branding.logoUrl` as documented under [session logo validation](/rest-api/reference/session-ui-settings.md#logo-validation).

## Read defaults

`GET /v1/Merchants/{merchantId}/profile/ui-settings`

`200 OK` returns the stored `MerchantUISettings` object. When the merchant has no stored UI defaults, the successful response body is JSON `null`; this means new sessions inherit Plexo defaults, not that the merchant is missing.

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `200`  | Stored settings returned, including `null` when no override exists.   |
| `401`  | Authentication is missing or invalid.                                 |
| `403`  | Authentication did not resolve a usable client identity.              |
| `404`  | Merchant not found or not owned by the client (`merchant-not-found`). |

## Replace defaults

`PUT /v1/Merchants/{merchantId}/profile/ui-settings`

The request replaces the complete stored object. A nested property omitted from the new body is removed from the merchant override and falls back to Plexo defaults for subsequently created sessions. Existing snapshots remain unchanged.

| Status | Meaning                                                                                                                                                 |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Replacement stored and returned.                                                                                                                        |
| `400`  | Null body, unknown/retired member, invalid enum, or palette color not in exact `#RRGGBB` format (`field-validation-error` or request validation error). |
| `401`  | Authentication is missing or invalid.                                                                                                                   |
| `403`  | Authentication did not resolve a usable client identity.                                                                                                |
| `404`  | Merchant not found or not owned by the client (`merchant-not-found`).                                                                                   |

## Reset defaults

`DELETE /v1/Merchants/{merchantId}/profile/ui-settings`

The operation clears the stored merchant UI object. New sessions use Plexo defaults unless their own session request supplies overrides. Existing session snapshots remain unchanged.

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `204`  | Defaults cleared; no response body.                                   |
| `401`  | Authentication is missing or invalid.                                 |
| `403`  | Authentication did not resolve a usable client identity.              |
| `404`  | Merchant not found or not owned by the client (`merchant-not-found`). |