# Currencies and exchange rates (/ai/reference/store/currencies)

Toolset `currencies`, 12 tools.

## Records [#records]

### `converted_price` [#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` [#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` [#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` [#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` [#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` [#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` [#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 [#actions]

### `currency_conversion_run` [#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:

```json
{}
```

### `currency_conversion_settings_update` [#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:

```json
{
  "currencies": {
    "eur": {
      "pricing": "converted",
      "source": "ecb",
      "base_per_unit": null,
      "margin_percent": 2,
      "rounding": "end_99"
    }
  }
}
```

### `reporting_currency_set` [#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:

```json
{
  "currency": "eur"
}
```

```json
{
  "currency": null
}
```

### `store_currency_settings_update` [#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:

```json
{
  "currency": "eur",
  "reason": "Selling mostly in the euro zone now"
}
```