Currency settings settings
Admin settings for the currency table (enabled, rate, rounding), the base currency and the default for new users; confirming the pre-upgrade accounting currency after upgrading from an old version.
Pick an endpoint to see its example call on the right.
Authentication
Send the X-API-Key header (create a key on the API Keys page; the key is shown only once at creation). An Authorization: Bearer token obtained by logging in also works.
X-API-Key
Authentication failures return 401; forbidden returns 403 (code such as insufficient_scope).
Conventions
Paging uses page (from 1) and page_size; sort with sort=field or sort=-field.
Times are RFC 3339 (UTC); amounts are in cents.
Writes return 200/201/204 on success; duplicates of a unique key return 409.
/api/v2/settings/currenciesGet currency settings
Authentication: Admin only
/api/v2/settings/currenciesCreate currency
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
codeRequired | string | Currency code (ISO 4217, 3 uppercase letters). |
enabled | boolean | Whether enabled |
minor_digits | integer | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). |
nameRequired | string | Name |
rate | string | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
rate_mode | string | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. |
rounding | string | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. |
symbolRequired | string | Display symbol such as ¥, US$, HK$. |
/api/v2/settings/currenciesUpdate currency settings
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
base_currency | string | Base currency: reports are converted into it; locked after the first order. |
default_currency | string | Default account currency for new users. |
fx_source | string | Exchange rate source. |
/api/v2/settings/currencies/fx/previewPreview exchange rates
Authentication: Admin only
/api/v2/settings/currencies/fx/refreshFetch exchange rates now
Authentication: Admin only
/api/v2/settings/currencies/{code}Update currency
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether enabled |
minor_digits | integer | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). |
name | string | Name |
rate | string | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
rate_mode | string | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. |
rounding | string | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. |
symbol | string | Display symbol such as ¥, US$, HK$. |
/api/v2/settings/currencies/{code}Delete currency
Authentication: Admin only
/api/v2/settings/currency-legacyGet legacy currency confirmation
Authentication: Admin only
/api/v2/settings/currency-legacyConfirm the accounting currency before the upgrade
Authentication: Admin only
Request body application/json
| Field | Type | Description |
|---|---|---|
currencyRequired | string | The accounting currency before the upgrade (ISO 4217); becomes the base currency and is stamped on existing accounts and orders (amounts are not converted). |
Currency settings object
| Field | Type | Description |
|---|---|---|
base_currency | string | Base currency: reports are converted into it; locked after the first order. |
base_locked | boolean | Orders exist, so the base currency can no longer be changed. |
can_reselect | boolean | Whether it can be (re)selected now: pending, or confirmed within 7 days with no new orders since the upgrade. |
codeRequired | string | Currency code (ISO 4217, 3 uppercase letters). |
currencies | Currency[] | Currency table (base currency first). |
currencyRequired | string | The accounting currency before the upgrade (ISO 4217); becomes the base currency and is stamped on existing accounts and orders (amounts are not converted). |
deadline | string | Deadline for reselecting (7 days after upgrade). |
default_currency | string | Default account currency for new users. |
enabled | boolean | Whether enabled |
fetched_at | string | Time the rates were fetched. |
fx_fetched_at | string | Last time the rate source returned this currency; auto cannot be selected while null. |
fx_source | string | Exchange rate source. |
fx_sources | string[] | Available exchange rate sources. |
max_deviation_pct | integer | Maximum percentage a refreshed auto rate may deviate from the old rate (beyond it the rate is rejected). |
minor_digits | integer | Display decimals: 2 = two decimals, 0 = none (JPY, KRW, ...); with 0, converted prices round to whole units and x99 tiers to ..99 or ..9 whole units. Amount fields still count 1/100 of the major unit. Omitted on create = ISO 4217 default (0 for zero-decimal currencies, else 2). |
nameRequired | string | Name |
rate | string | 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places. |
rate_mode | string | Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand. |
rate_updated_at | string | Last time the rate changed. |
rates | object | Currency → 1 unit = ? base currency (decimal string); includes currencies not in the table, base is 1. |
rejected | string[] | Currencies whose new rate was not applied because it deviated more than max_deviation_pct from the old rate (auto-mode rows; the old rate and timestamp are kept). Empty if none. |
rounding | string | Price rounding: none, or x99 = tiered: try .99, then .x9, and take the first whose premium over the exact converted price is at most 10%; if both exceed it, keep the exact price. |
saved | string[] | Currencies whose rate was saved this time (rows in auto mode). |
source | string | Exchange rate source used this time. |
state | string | unset = not yet judged, pending = awaiting confirmation, confirmed, auto_cny = set to CNY automatically, none = fresh install. |
symbolRequired | string | Display symbol such as ¥, US$, HK$. |
unopened_users | integer | Tenants without an account row yet: they are priced in the new-user default currency and counted in its user_count; changing the default currency moves them too. |
user_count | integer | Number of users whose account currency is this one. |
Responses and errors
Success returns the resource JSON directly (HTTP 2xx); failures return application/problem+json (code, detail, plus errors on validation failures); lists carry items + total.
{
"id": 1,
"name": "example"
}{
"items": [
{
"id": 1
}
],
"page": 1,
"page_size": 20,
"total": 1
}{
"code": "validation_failed",
"detail": "Invalid request parameters",
"errors": [
{
"code": "required",
"field": "/name",
"message": "name is required"
}
],
"request_id": "0123456789abcdef",
"status": 422,
"title": "Unprocessable Entity",
"type": "about:blank"
}