Skip to content

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.

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
}
]
}

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)

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)

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"

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.

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.

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.

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.

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.

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"}.

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)

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"