---
title: "Create a terminal theme"
method: POST
path: "/merchants/{merchantId}/terminalThemes"
tags: ["Terminal themes - merchant level"]
---

# Create a terminal theme

`POST /merchants/{merchantId}/terminalThemes`

## Request

- Base URL: `https://management-test.adyen.com/v3`
- URL: `https://management-test.adyen.com/v3/merchants/{merchantId}/terminalThemes`
- Auth: one of:
  - HTTP basic
  - API key in header `X-API-Key`

Creates a terminal theme for the merchant account specified in the path, to customize screens shown on Android payment terminals. This request only creates a basic theme with a name and a dark or light mode. We refer to this as the metadata of the theme. 

Next steps are to add terminal model-specific assets (images or videos) to the theme, and to apply (activate) the theme. 

The theme name must be unique for the merchant account; other accounts can have a theme with the same name. 

To make this request, your API credential must have the following [role](https://docs.adyen.com/development-resources/api-credentials#manage-api-permissions):
- Management API - Terminal themes read and write

## Path parameters

- `merchantId` string, required

## Request body

- CreateThemeRequest: The request body for creating a new terminal theme.
  - `mode` 'dark' | 'light', required: The terminal display mode. Possible values: **dark**, **light**.
  - `name` string, required: The name of the theme. Must be unique within the account specified in the path. Maximum 255 characters.

## Response `201`

Created

- CreateThemeResponse: The response containing the created terminal theme details.
  - `id` string, required: The unique identifier of the theme. This value is generated by Adyen.
  - `mode` 'dark' | 'light', required: The terminal display mode. Possible values: **dark**, **light**.
  - `name` string, required: The name of the theme.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `500`: Internal Server Error

## Changes

- **2026-09-23** (v3) `55cb8143ce0e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/adyen/apis/management-api/changes/merchants/:merchantId/terminalThemes/post.md)

---

[API](https://skmtc.dev/adyen/apis/management-api.md) - [All operations](https://skmtc.dev/adyen/apis/management-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adyen/apis/management-api/revisions/55cb8143ce0e?raw)