> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hel.io/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).

<Info>
  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).
</Info>

## 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.

<Info>
  Presets (**MoonPay Purple** and **MoonPay Mono**) are available out of the box. You can start from a preset and save your own variations.
</Info>

### 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) for request/response details.

<Info>
  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.
</Info>