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

# Overview

> Assign a theme to a deposit, pay link, or withdrawal by ID, and read the resolved theme returned on public payloads.

Themes are **created and managed in the [Dashboard](https://moonpay.hel.io/)** (Settings → Themes). The public API does **not** create or edit themes — it lets you **assign** an existing theme to a product by its ID, and it returns the **resolved theme** on public payloads so your integration can render it.

For an overview of what a theme is and how appearance is resolved, see the [Themes guide](/docs/themes).

## Finding a theme's ID

Open a theme under **Settings → Themes** in the Dashboard and copy its **theme ID** from the editor. This is the value you pass as `themeId`.

## Assigning a theme by ID

Pass the optional `themeId` in the request body when creating or updating a product with your API key:

| Product    | Create                                | Update                                                      |
| ---------- | ------------------------------------- | ----------------------------------------------------------- |
| Deposit    | `POST /v1/deposits/create/api-key`    | `PATCH /v1/deposits/{depositId}/api-key`                    |
| Pay link   | `POST /v1/paylink/create/api-key`     | `PATCH /v1/paylink/{id}/api-key`                            |
| Withdrawal | `POST /v1/withdrawal-configs/api-key` | `PATCH /v1/withdrawal-configs/{withdrawalConfigId}/api-key` |

If `themeId` is omitted, the product falls back to your **company default theme**, then the preset default, then the buyer's system preference (see [appearance resolution](/docs/themes#how-appearance-is-resolved)).

### Example

```shell theme={null}
curl --location 'https://api.hel.io/v1/deposits/create/api-key?apiKey=<YOUR_PUBLIC_API_KEY>' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_API_KEY' \
--data '{
    "name": "My deposit",
    "themeId": "665f0a1b2c3d4e5f60718293"
}'
```

## The resolved `theme` object

Public payloads for deposits, pay links, and charges include the assigned `themeId` and a resolved `theme` object so you can render the correct appearance. Colors are supplied for both **light** and **dark**; render the variant that matches the buyer's system preference (or your forced `themeMode`).

```json theme={null}
{
  "id": "665f0a1b2c3d4e5f60718293",
  "name": "Brand theme",
  "type": "CUSTOM",
  "light": {
    "primaryColor": "#7D00FF",
    "neutralColor": "#5A6578",
    "backgroundColor": "#FFFFFF",
    "successColor": "#1F9D55",
    "dangerColor": "#E5484D",
    "warningColor": "#F5A623"
  },
  "dark": {
    "primaryColor": "#9B5CFF",
    "neutralColor": "#8A94A6",
    "backgroundColor": "#0B0B0F"
  },
  "designTokens": {
    "containerBorderRadius": 16,
    "inputBorderRadius": 8,
    "buttonBorderRadius": 8,
    "containerBorderWidth": 1,
    "inputBorderWidth": 1,
    "padding": 24,
    "fontFamily": "Inter"
  },
  "isDefault": false,
  "createdAt": "2026-08-01T12:00:00.000Z",
  "updatedAt": "2026-08-01T12:00:00.000Z"
}
```

### Theme object fields

| Field                     | Type    | Description                                     |
| ------------------------- | ------- | ----------------------------------------------- |
| `id`                      | string  | Theme ID — the value you pass as `themeId`.     |
| `name`                    | string  | Theme name.                                     |
| `type`                    | string  | `CUSTOM` for merchant themes, or a preset type. |
| `light`                   | Palette | Light-mode palette (see below).                 |
| `dark`                    | Palette | Dark-mode palette.                              |
| `designTokens`            | Tokens  | Shared radii, border widths, padding, and font. |
| `isDefault`               | boolean | Whether this is a default/preset theme.         |
| `createdAt` / `updatedAt` | string  | ISO-8601 timestamps.                            |

**Palette:** `primaryColor`, `neutralColor`, `backgroundColor` (all required hex); `successColor`, `dangerColor`, `warningColor` (optional hex).

**Tokens:** `containerBorderRadius`, `inputBorderRadius`, `buttonBorderRadius`, `containerBorderWidth`, `inputBorderWidth`, `padding`, and `fontFamily` (optional).

<Info>
  To create or edit the themes themselves, use the Dashboard (**Settings → Themes**). See the [Themes guide](/docs/themes).
</Info>