---
title: "Create custom currency"
method: POST
path: "/openmeter/currencies/custom"
tags: ["OpenMeter Currencies"]
---

# Create custom currency

`POST /openmeter/currencies/custom`

Create a custom currency. This operation allows defining your own custom
currency for billing purposes.

## Request body

- CreateCurrencyCustomRequest — CurrencyCustom create request.
  - `name` string, required — The name of the currency. It should be a human-readable string that represents the name of the currency, such as "US Dollar" or "Euro".
  - `symbol` string — The symbol of the currency. It should be a string that represents the symbol of the currency, such as "$" for US Dollar or "€" for Euro.
  - `precision` integer, required — The precision of the currency. It should be a number that represents the number of decimal places used for the currency, such as 2 for US Dollar or Euro.
  - `decimal_mark` string, required — The decimal mark for the currency. It should be a string that represents the decimal mark of the currency, such as "." for US Dollar or "," for Euro.
  - `thousand_separator` string, required — The thousand separator for the currency. It should be a string that represents the thousand separator of the currency, such as "," for US Dollar or "." for Euro.
  - `code` string, required — Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes.

## Response `201`

CurrencyCustom created response.

- BillingCurrencyCustom — Describes custom currency.
  - `type` 'custom', required — The type of the currency.
  - `name` string, required — The name of the currency. It should be a human-readable string that represents the name of the currency, such as "US Dollar" or "Euro".
  - `symbol` string — The symbol of the currency. It should be a string that represents the symbol of the currency, such as "$" for US Dollar or "€" for Euro.
  - `precision` integer, required — The precision of the currency. It should be a number that represents the number of decimal places used for the currency, such as 2 for US Dollar or Euro.
  - `decimal_mark` string, required — The decimal mark for the currency. It should be a string that represents the decimal mark of the currency, such as "." for US Dollar or "," for Euro.
  - `thousand_separator` string, required — The thousand separator for the currency. It should be a string that represents the thousand separator of the currency, such as "," for US Dollar or "." for Euro.
  - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
  - `code` string, required — Custom currency code. It should be a unique code but not conflicting with any existing fiat currency codes.
  - `created_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
  - `cost_basis` BillingCostBasis[] — The list of active and scheduled cost bases for the custom currency. Expired and deleted cost bases are excluded.
    - `id` string, required — ULID (Universally Unique Lexicographically Sortable Identifier).
    - `fiat_code` string, required — Three-letter [ISO4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. Custom three-letter currency codes are also supported for convenience.
    - `rate` string, required — Numeric represents an arbitrary precision number.
    - `effective_from` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `effective_to` string, date-time — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.
    - `created_at` string, date-time, required — [RFC3339](https://tools.ietf.org/html/rfc3339) formatted date-time string in UTC.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden

## Changes

- **2026-07-20** (v3) `e7222bb0aca6` — 4 breaking, 4 info
  - added the new required request property `decimal_mark`
  - added the new required request property `precision`
  - added the new required request property `thousand_separator`
  - the `code` request property's minLength was increased from `3` to `4`
  - …4 more
- **2026-07-01** (v3) `2992df87e05c` — 2 warning
  - removed the request property `description`
  - removed the optional property `description` from the response with the `201` status
- **2026-06-18** (v3) `8ca194cd4b6f` — 2 info
  - api tag `OpenMeter Currencies` added
  - api tag `OpenMeter Billing` removed
- **2026-05-11** (v3) `9d0042cb3815` — 4 info
  - api tag `OpenMeter Billing` added
  - api tag `OpenMeter Currencies` removed
  - added the new optional request property `description`
  - added the optional property `description` to the response with the `201` status

[Change history](https://skmtc.dev/openmeterio/apis/openmeter-api/changes/openmeter/currencies/custom/post.md)

---

[API](https://skmtc.dev/openmeterio/apis/openmeter-api.md) · [All operations](https://skmtc.dev/openmeterio/apis/openmeter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openmeterio/openmeter-api/revisions/3e66c224fc9b/schema)