Version 2.4.7.20261116085428 · latest

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.

BillingAuthentication: Admin only9 endpoints

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.

POST/api/v2/settings/currenciesCreate currency

Authentication: Admin only

Request body application/json

FieldTypeDescription
codeRequiredstring Currency code (ISO 4217, 3 uppercase letters).
enabledboolean Whether enabled
minor_digitsinteger 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).
Values [0,2]
nameRequiredstring Name
ratestring 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places.
rate_modestring Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand.
Values ["auto","manual"]
roundingstring 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.
Values ["none","x99"]
symbolRequiredstring Display symbol such as ¥, US$, HK$.
PUT/api/v2/settings/currenciesUpdate currency settings

Authentication: Admin only

Request body application/json

FieldTypeDescription
base_currencystring Base currency: reports are converted into it; locked after the first order.
default_currencystring Default account currency for new users.
fx_sourcestring Exchange rate source.
POST/api/v2/settings/currencies/fx/refreshFetch exchange rates now

Authentication: Admin only

PUT/api/v2/settings/currencies/{code}Update currency

Authentication: Admin only

Request body application/json

FieldTypeDescription
enabledboolean Whether enabled
minor_digitsinteger 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).
Values [0,2]
namestring Name
ratestring 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places.
rate_modestring Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand.
Values ["auto","manual"]
roundingstring 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.
Values ["none","x99"]
symbolstring Display symbol such as ¥, US$, HK$.
POST/api/v2/settings/currency-legacyConfirm the accounting currency before the upgrade

Authentication: Admin only

Request body application/json

FieldTypeDescription
currencyRequiredstring 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

FieldTypeDescription
base_currencystring Base currency: reports are converted into it; locked after the first order.
base_lockedboolean Orders exist, so the base currency can no longer be changed.
can_reselectboolean Whether it can be (re)selected now: pending, or confirmed within 7 days with no new orders since the upgrade.
codeRequiredstring Currency code (ISO 4217, 3 uppercase letters).
currenciesCurrency[] Currency table (base currency first).
currencyRequiredstring The accounting currency before the upgrade (ISO 4217); becomes the base currency and is stamped on existing accounts and orders (amounts are not converted).
deadlinestring Deadline for reselecting (7 days after upgrade).
default_currencystring Default account currency for new users.
enabledboolean Whether enabled
fetched_atstring Time the rates were fetched.
fx_fetched_atstring Last time the rate source returned this currency; auto cannot be selected while null.
fx_sourcestring Exchange rate source.
fx_sourcesstring[] Available exchange rate sources.
max_deviation_pctinteger Maximum percentage a refreshed auto rate may deviate from the old rate (beyond it the rate is rejected).
minor_digitsinteger 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).
Values [0,2]
nameRequiredstring Name
ratestring 1 unit of this currency = ? base currency; greater than 0, up to 8 decimal places.
rate_modestring Rate mode: auto = fetched periodically from the rate source (must have been fetched once), manual = entered by hand.
Values ["auto","manual"]
rate_updated_atstring Last time the rate changed.
ratesobject Currency → 1 unit = ? base currency (decimal string); includes currencies not in the table, base is 1.
rejectedstring[] 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.
roundingstring 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.
Values ["none","x99"]
savedstring[] Currencies whose rate was saved this time (rows in auto mode).
sourcestring Exchange rate source used this time.
statestring unset = not yet judged, pending = awaiting confirmation, confirmed, auto_cny = set to CNY automatically, none = fresh install.
Values ["unset","pending","confirmed","auto_cny","none"]
symbolRequiredstring Display symbol such as ¥, US$, HK$.
unopened_usersinteger 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_countinteger 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.

Success
{
  "id": 1,
  "name": "example"
}
List
{
  "items": [
    {
      "id": 1
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1
}
Error
{
  "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"
}
Get started

Try the live demo

Open the live demo, or contact us for a quote and the install command