Currencies and exchange rates
The 12 tools of the Currencies and exchange rates toolset in the Store area, with their permissions, approval rules and inputs.
On this page
Toolset currencies, 12 tools.
Records
converted_price
Which prices of the given price sets the currency conversion wrote, with the written amount and any amount still pending. A price in a converted currency that is not listed is a fixed price. Take price set ids from a product variant.
- Permission:
products.read - Tools:
converted_price_list
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
price_set_id | list of string | yes | 1 to 200 items |
currency
A currency the platform knows, by lower-case ISO code (huf, eur), with its name, symbol and decimal digits. The ones the store sells in are on the store record.
- Permission:
settings.read - Tools:
currency_list,currency_get - Sorts:
code,name
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
q | string | Search by name or code |
currency_conversion
How prices in each non-default currency are converted from the store currency: the setting, the rate in use, the rates the two sources quote today, how many prices are converted and how many fixed, and when the last run was. There is one record; pass any id, e.g. "current". Change the settings with currency_conversion_settings_update.
- Permission:
settings.read - Tools:
currency_conversion_get
currency_conversion_settings
Per non-default currency, how its prices follow the store currency: converted by exchange rate or manual, the rate source (ecb, mnb or a fixed rate), the margin and the rounding of the converted price. Currencies not listed use the defaults (converted, ecb, no margin). There is one record; pass any id, e.g. "current".
- Permission:
settings.read - Tools:
currency_conversion_settings_get
exchange_rate_status
Whether the store has exchange rates, from which sources, and how fresh they are. There is one record; pass any id, e.g. "current".
- Permission:
settings.read - Tools:
exchange_rate_status_get
order_exchange_rate
The rate frozen for each asked order when it was converted to the reporting currency, with its source and day, and the orders' total in the reporting currency.
- Permission:
orders.read - Tools:
order_exchange_rate_list
Filters on the list:
| Filter | Type | Required | Description |
|---|---|---|---|
order_id | list of string | yes | 1 to 200 items |
store_currency_settings
The currency the store prices in and the one its reports are in (the reporting currency, which follows the store currency unless set), the exchange-rate source, whether the store has orders, whether the viewer is the owner, the currencies the rates cover, a running analytics rebuild and the change history. There is one record; pass any id, e.g. "current".
- Permission:
settings.read - Tools:
store_currency_settings_get
Actions
currency_conversion_run
Fetch today's rates and rewrite the converted prices now, instead of waiting for the daily run.
It answers at once; currency_conversion_get shows the new last_run_at when it is done. Prices in a currency set to manual pricing are not touched.
- Action key:
currency_conversion.run - Permission:
settings.write - Approval: Waits for approval when the store requires it for this action.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
Takes no input.
Example input:
{}currency_conversion_settings_update
Set how the prices of one or more currencies are converted from the store currency.
currencies maps a lower-case currency code to its whole setting; a currency not named keeps its setting, and null returns one to the defaults. A changed setting rewrites the converted prices at the next conversion run (currency_conversion_run starts one).
- Action key:
currency_conversion_settings.update - Permission:
settings.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
currencies | map of object or null | yes |
Example input:
{
"currencies": {
"eur": {
"pricing": "converted",
"source": "ecb",
"base_per_unit": null,
"margin_percent": 2,
"rounding": "end_99"
}
}
}reporting_currency_set
Choose the currency reports and analytics are shown in, or make them follow the store currency.
currency null follows the store currency. Orders in other currencies are converted at the rate frozen per order; analytics are recalculated afterwards.
- Action key:
reporting_currency.set - Permission:
settings.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
currency | string or null | yes | |
expected_version | integer | at least 0 |
Example inputs:
{
"currency": "eur"
}{
"currency": null
}store_currency_settings_update
Change the currency the store prices in, and optionally the reporting currency with it.
Once the store has orders only the store owner can change it, and acknowledge must be the new currency code; send that only after the merchant confirmed the change in words. covered_currencies in store_currency_settings_get lists the currencies with exchange-rate coverage. Analytics are recalculated afterwards. reporting_currency null follows the store currency.
- Action key:
store_currency_settings.update - Permission:
settings.write - Approval: Always waits for a person to approve it.
- Effect: Changes the live store.
- Retries: safe to repeat with the same input.
| Field | Type | Required | Description |
|---|---|---|---|
currency | string | yes | |
acknowledge | string or null | at most 16 characters | |
reason | string or null | at most 500 characters | |
reporting_currency | string or null | ||
expected_version | integer | at least 0 |
Example input:
{
"currency": "eur",
"reason": "Selling mostly in the euro zone now"
}