> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Currencies and exchange rates (v2)

> Get the base currency, the business's active currencies, and their exchange rates

**Required permission:** `currencies` (assigned in **External integrations**; integrations with legacy full access already include it)

These endpoints are read-only and exist only in v2 (`https://api.filexpress.app/api/external/v2`). Use them to find out which currencies you can issue documents in and which rate will be applied, before calling [Create sale](https://docs.filexpress.app/en/docs/api/v2/ventas.md#create-sale) or [Register purchase](https://docs.filexpress.app/en/docs/api/v2/compras.md#register-a-purchase).

> [!NOTE]
>
> If the business does not have multi-currency enabled, all three endpoints respond `403` with `code: "currency_not_enabled"`. Without the `currencies` permission they respond `403` with `required_scope: "currencies"`.

## List currencies

```http theme={null}
GET /currencies
```

Returns the business's base currency and the active foreign currencies.

```json theme={null}
{
  "status": true,
  "data": {
    "base_currency_code": "USD",
    "currencies": [
      { "code": "USD", "name": "Dólar estadounidense", "symbol": "$", "decimals": 2, "is_base": true },
      { "code": "GTQ", "name": "Quetzal guatemalteco", "symbol": "Q", "decimals": 2, "is_base": false }
    ]
  }
}
```

| Field | Description |
| - | - |
| `base_currency_code` | The business's base currency, in which all documents are stored and accounted for. |
| `currencies[].code` | 3-letter code you send in `currency_code`. |
| `currencies[].name` / `symbol` | Currency name and symbol. |
| `currencies[].decimals` | Decimals used to round amounts in that currency. |
| `currencies[].is_base` | `true` only for the base currency. |

Only the base currency and the business's **active** foreign currencies appear; an inactive currency cannot be used in documents (`currency_not_enabled`).

## List exchange rates

```http theme={null}
GET /exchange-rates?currency=GTQ&from=2026-10-01&to=2026-10-31&per_page=50
```

| Parameter | Type | Required | Description |
| - | - | - | - |
| `currency` | string | No | Currency code (for example `GTQ`). Without it, all currencies. |
| `from` | date | No | Effective date from (`YYYY-MM-DD`). |
| `to` | date | No | Effective date to (`YYYY-MM-DD`). |
| `per_page` | integer | No | 1 to 200. Default 50. |
| `page` | integer | No | Page. |

Sorted from newest to oldest. Only the rates of the integration's business are listed.

```json theme={null}
{
  "status": true,
  "data": {
    "base_currency_code": "USD",
    "rates": [
      { "id": "9a10c2f4-...", "currency_code": "GTQ", "rate": "0.13000000", "effective_date": "2026-10-20", "source": "manual" },
      { "id": "7b31d8e0-...", "currency_code": "GTQ", "rate": "0.12800000", "effective_date": "2026-10-15", "source": "manual" }
    ],
    "current_page": 1,
    "last_page": 1,
    "per_page": 50,
    "total": 2
  }
}
```

| Field | Description |
| - | - |
| `rates[].rate` | Units of **base** currency per 1 unit of the foreign currency, as text with 8 decimals. |
| `rates[].effective_date` | Date from which the rate is in effect. |
| `rates[].source` | Origin of the rate: `manual` or `api`. |

> [!NOTE]
>
> This listing is not paginated with the `pagination` object used in other modules: pagination comes as `current_page`, `last_page`, `per_page`, and `total` inside `data`.

## Resolve a document's rate

```http theme={null}
GET /exchange-rates/resolve?branch_id={branch_id}&currency=GTQ&date=2026-10-17
```

Returns the rate FileXpress would use for a document of that branch, currency, and date: the rate for that day or, if there is none, the latest earlier one. A branch-specific rate takes priority over the business-wide one.

| Parameter | Type | Required | Description |
| - | - | - | - |
| `branch_id` | uuid | Yes | Branch of the integration's business. See `GET /branches` in v1. |
| `currency` | string | Yes | 3-letter code. Must be the base currency or an active currency. |
| `date` | date | No | Document date. Defaults to today. |

```json theme={null}
{
  "status": true,
  "data": {
    "currency_code": "GTQ",
    "base_currency_code": "USD",
    "rate": "0.12800000",
    "effective_date": "2026-10-15",
    "exact": false,
    "source": "manual"
  }
}
```

| Field | Description |
| - | - |
| `rate` | Rate that would be applied (units of base per 1 unit of the currency). |
| `effective_date` | Date of the rate found. |
| `exact` | `true` if the rate is from the same date requested; `false` if an earlier one was used. |
| `source` | `manual`, `api`, or `base` (when you query the base currency, with rate `1.00000000`). |

**Errors**

| `code` | HTTP | Cause |
| - | - | - |
| `validation_error` | `422` | `currency` missing or not 3 letters long, or `branch_id` that does not belong to the business. |
| `currency_not_enabled` | `422` | The currency is not active for the business. |
| `exchange_rate_not_found` | `404` | There is no rate on that date or earlier. Register a rate in FileXpress or send `exchange_rate` in the document. |

```json theme={null}
{
  "status": false,
  "code": "exchange_rate_not_found",
  "message": "No hay tasa de cambio para GTQ a la fecha 2026-10-01 ni anterior. Registre una tasa de cambio o envíe exchange_rate en el documento.",
  "errors": { "exchange_rate": "Sin tasa de cambio para GTQ al 2026-10-01." }
}
```

> [!TIP]
>
> To avoid surprises, resolve the rate with the document's date before issuing it and send it as `exchange_rate` if your system has already fixed it (for example, the day's cash register rate). If you don't send it, the server applies the same resolution.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.