> ## Documentation Index
> Fetch the complete documentation index at: https://dev.commerce.moonpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Themes

> Create reusable, named themes with light and dark palettes and assign them to your deposits, pay links, and withdrawals.

Themes let you save **named, reusable brand styles** and apply them across your MoonPay Commerce products — **Deposits**, **Pay Links**, and **Withdrawals**. Each theme carries a full **light *and* dark palette** plus shared design tokens (corner radii, border widths, padding, and font).

> [!NOTE]
>
> Themes are authored in the **Dashboard**. You assign them to a product either by picking one in the product's create/edit flow, by setting a **company default**, or by passing a `themeId` when you create the product [via the API](/reference/theme/overview.md).

## How appearance is resolved

Two **independent** things decide how a deposit, pay link, or withdrawal looks — one picks the colors, the other picks light vs dark:

**Which colors — the theme.** Resolved in this order:

1. **Theme assigned to the product** — the `themeId` set on that specific deposit / pay link / withdrawal.
2. **Company default theme** — the theme you mark as default under **Settings → Themes**.
3. **Preset default** — MoonPay's built-in default (**MoonPay Mono**).

**Light or dark — the mode.** Every theme carries both a light and a dark palette; the mode selects which one renders:

1. The embed's [`themeMode`](/docs/checkout-widget) value, if set — forces light or dark.
2. Otherwise the buyer's **system light/dark preference**.

The two combine: a merchant using a custom theme who sets `themeMode: 'dark'` gets **that theme's dark palette**. Leaving `themeMode` unset shows whichever of the theme's palettes matches the buyer's system setting — `themeMode` never replaces the theme, it just picks the palette.

## Create a theme

1. Go to **Settings → Themes** in the [Dashboard](https://moonpay.hel.io/).
2. Click **Add Theme** and give it a name.
3. Set the **Light** and **Dark** palettes and the shared **design tokens** (see below). A live preview shows how deposits, pay links, and charges will look.
4. Save, then choose it as your **Active theme** by clicking on it.

> [!NOTE]
>
> Presets (**MoonPay Purple** and **MoonPay Mono**) are available out of the box. You can start from a preset and save your own variations.

### Palette (per light and dark)

Each palette is a set of hex colors.

| Field | Required | Description |
| - | - | - |
| `primaryColor` | Yes | Brand seed — buttons and interactive elements. |
| `neutralColor` | Yes | Neutral seed — text, surfaces, and borders. |
| `backgroundColor` | Yes | Page / surface background. |
| `successColor` | No | Success state. |
| `dangerColor` | No | Error / danger state. |
| `warningColor` | No | Warning state. |

Colors must be valid hex (e.g. `#7D00FF`). Text color on buttons is derived automatically for contrast — you don't set it.

### Design tokens (shared across light and dark)

| Field | Description |
| - | - |
| `containerBorderRadius` | Corner radius of cards / containers. |
| `inputBorderRadius` | Corner radius of inputs. |
| `buttonBorderRadius` | Corner radius of buttons. |
| `containerBorderWidth` | Container border thickness. |
| `inputBorderWidth` | Input border thickness. |
| `padding` | Container padding. |
| `fontFamily` | Font family name (optional). |

## Assign a theme

### In the Dashboard

When creating or editing a deposit, pay link, or withdrawal, pick a saved theme in the flow. If you don't pick one, the product uses your **company default theme**.

### By ID via the API

When you create or update a product with an API key, pass the theme's `themeId`:

* Deposits — `POST /v1/deposits/create/api-key`, `PATCH /v1/deposits/{depositId}/api-key`
* Pay links — `POST /v1/paylink/create/api-key`, `PATCH /v1/paylink/{id}/api-key`
* Withdrawals — `POST /v1/withdrawal-configs/api-key`, `PATCH /v1/withdrawal-configs/{withdrawalConfigId}/api-key`

You can find and copy a theme's ID from the theme editor in **Settings → Themes**. See the [Themes API reference](/reference/theme/overview.md) for request/response details.

> [!NOTE]
>
> Themes are **created and edited in the Dashboard only** — there is no public API to create or edit themes. The API lets you **assign** an existing theme by ID and returns the resolved theme on public payloads.