Overview

Themes are created and managed in the Dashboard (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.

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

Example

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

{
  "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).

To create or edit the themes themselves, use the Dashboard (Settings → Themes). See the Themes guide.

API

WALLET

CURRENCY

THEMES

PAY LINKS

TRANSACTIONS

SUBSCRIPTIONS

CHARGES

DEPOSITS

WITHDRAWALS

WEBHOOKS

HEADLESS PAYMENTS

ALLOW LIST

PLATFORM

EXPORTS

Finding a theme’s ID

Assigning a theme by ID

Example

The resolved `theme` object

Theme object fields

​Finding a theme’s ID

​Assigning a theme by ID

​Example

​The resolved theme object

​Theme object fields

Finding a theme’s ID

Assigning a theme by ID

Example

The resolved `theme` object

Theme object fields