Currencies API
Clients are billed in one of the portal’s currencies. Each currency has a conversion rate from the default currency and optional display formatting. See Currencies for how they work.
Admin calls need Module access on the Currency card of the staff group’s Permissions tab, plus each call’s own permission below (Super Administrators have all). See Authentication.
Admin calls
Section titled “Admin calls”get_list
Section titled “get_list”POST /api/admin/currency/get_list
Lists the portal’s currencies, sorted by code.
Permission: View currencies (currency.view)
| Parameter | Type | Description |
|---|---|---|
search |
string | Part of a currency code. |
page |
integer | Page number, from 1. Default 1. |
per_page |
integer | Rows per page, 1 to 500. Default 100. |
Returns: A paged list. Each row is a currency as in get.
Example
Request parameters:
{}result:
{ "pages": 1, "page": 1, "per_page": 100, "total": 2, "list": [ { "code": "EUR", "name": "Euro", "symbol": "€", "conversion_rate": 0.92, "is_rate_manual": false, "format_pattern": null, "fraction_digits": null, "default": false }, { "code": "USD", "name": "US Dollar", "symbol": "$", "conversion_rate": 1, "is_rate_manual": false, "format_pattern": null, "fraction_digits": null, "default": true } ]}get_pairs
Section titled “get_pairs”POST /api/admin/currency/get_pairs
Lists every ISO currency that is in use in some country, for choosing a currency to add.
Permission: View currencies (currency.view)
No parameters.
Returns: An object of code => label, such as {"EUR": "EUR (Euro)", "USD": "USD (US Dollar)"}. Names are in the staff member’s language.
POST /api/admin/currency/get
Returns one currency.
Permission: View currencies (currency.view)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The currency code, such as EUR. |
Returns: code, name, symbol, conversion_rate (how many units of this currency one unit of the default currency buys), is_rate_manual (rate updates leave it alone), format_pattern (such as {amount} €, or null), fraction_digits (decimals shown, or null for the currency’s own) and default.
Errors:
- Currency not found. (code 9999)
get_default
Section titled “get_default”POST /api/admin/currency/get_default
Returns the default currency.
Permission: View currencies (currency.view)
No parameters.
Returns: The currency, as in get.
Errors:
- Default currency not found (code 9999)
create
Section titled “create”POST /api/admin/currency/create
Adds a currency. Without a rate, the current exchange rate is fetched from the configured provider (1 when that fails).
Permission: Create Currencies (currency.create)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | An ISO 4217 code, such as EUR. |
conversion_rate |
number | Units of this currency per unit of the default currency; a positive number. |
is_rate_manual |
boolean | Keep this rate when rates are updated. Needs conversion_rate. |
Returns: The new currency’s code.
Errors:
- Currency already registered. (code 9999)
- Currency code is invalid. (code 9999)
- Currency conversion rate must be a positive number. (code 9999)
- A conversion rate is required when manual override is enabled. (code 9999)
Example
Request parameters:
{ "code": "EUR", "conversion_rate": 0.92}result:
"EUR"update
Section titled “update”POST /api/admin/currency/update
Changes a currency’s rate, manual-rate switch and display formatting. Only the fields you send change.
Permission: Edit Currencies (currency.edit)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The currency code. |
conversion_rate |
number | A positive rate. |
is_rate_manual |
boolean | Keep this rate when rates are updated. Not allowed for the default currency. |
format_pattern |
string | How prices show: one line of text with exactly one {amount}, up to 100 characters, such as {amount} kr. Empty uses the standard format. |
fraction_digits |
integer | Decimals shown, 0 to 6. Empty uses the currency’s own. |
Returns: true.
Errors:
- Currency not found. (code 9999)
- Currency conversion rate is invalid. (code 151)
- The default currency cannot use a manual rate override. (code 9999)
- Currency format pattern must contain exactly one {amount} placeholder. (code 9999)
- Currency fraction digits must be a whole number between 0 and 6. (code 9999)
Fixed product prices in this currency are worked out again with the new rate.
is_cron_enabled
Section titled “is_cron_enabled”POST /api/admin/currency/is_cron_enabled
Whether exchange rates are updated automatically (the rate update setting is not “never”).
Permission: View currencies (currency.view)
No parameters.
Returns: true or false.
update_rates
Section titled “update_rates”POST /api/admin/currency/update_rates
Fetches current exchange rates now for every currency without a manual rate.
Permission: Update Currency Rates (currency.update_rates)
No parameters.
Returns: true.
Errors:
- Default currency not found. Cannot update rates. (code 9999)
- The provider’s error, such as a missing API key, when a rate cannot be fetched.
delete
Section titled “delete”POST /api/admin/currency/delete
Deletes a currency. The default currency cannot be deleted.
Permission: Delete Currencies (currency.delete)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The currency code. |
Returns: true.
Errors:
- Currency not found. (code 9999)
- Cannot remove the default currency. (code 9999)
Fixed product prices in this currency are deleted with it. Fires the currency delete events.
set_default
Section titled “set_default”POST /api/admin/currency/set_default
Makes a currency the default. Every rate is recalculated against the new default.
Permission: Set Default Currency (currency.set_default)
| Parameter | Type | Description |
|---|---|---|
code |
string, required | The currency code. |
Returns: true (also when it is already the default).
Errors:
- Currency not found. (code 9999)
The new default’s rate becomes 1 and its manual-rate switch is turned off.
Guest calls
Section titled “Guest calls”get_pairs (guest)
Section titled “get_pairs (guest)”POST /api/guest/currency/get_pairs
Lists the portal’s currencies.
No parameters.
Returns: An object of code => name, sorted by code, such as {"EUR": "Euro", "USD": "US Dollar"}.
get (guest)
Section titled “get (guest)”POST /api/guest/currency/get
Returns a currency, or the default currency when no code is sent.
| Parameter | Type | Description |
|---|---|---|
code |
string | The currency code. Default: the default currency. |
Returns: The currency, as in the admin get.
Errors:
- Currency not found. (code 9999)
format (guest)
Section titled “format (guest)”POST /api/guest/currency/format
Formats a price in a currency, in the visitor’s language, as the portal shows prices.
| Parameter | Type | Description |
|---|---|---|
price |
number | The price. Default 0. |
code |
string | The currency code. Default: the default currency. |
convert |
boolean | Default true: the price is in the default currency and is converted with the currency’s rate first. |
without_currency |
boolean | Return the number only, without the currency symbol. Default false. |
Returns: The formatted price as a string, such as "€9.20".
Errors:
- Currency not found. (code 9999)
Example
Request parameters:
{ "price": 10, "code": "EUR"}result:
"€9.20"
