Skip to main content
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).
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.

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

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