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

# API reference exchange rates

> Retrieve conversion rates for display-currency conversion through the Admin Interface API: a rate bundle relative to a target currency including a recency flag.

The `exchange-rates` endpoint returns a bundle of current exchange rates that can be used to convert amounts from any known currency into a freely selectable target currency.

The rates are based on the reference rates obtained from the European Central Bank (ECB). Internally these rates are stored relative to the base currency **EUR**; the endpoint derives the cross rates to the requested target currency from them. Among other things, the interface is used by the Admin Interface to display amounts locally in the selected display currency without requiring a separate request for each conversion.

<Note>
  The exchange rates are fetched daily from the ECB. The endpoint always returns the most recent exchange rate known to the shop.
</Note>

Using this endpoint requires a valid login (see [API Basics](/en/schnittstellen/admin-interface-api/api-basics)). No service-specific permission is required.

***

## Supported methods

Overview of all supported methods.

| **Command/Info**   | **Endpoints**  | **GET**               | **POST**            | **PUT**             | **DELETE**          |
| ------------------ | -------------- | --------------------- | ------------------- | ------------------- | ------------------- |
| **Exchange rates** | exchange-rates | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |

## Data fields of a rate entry

Each entry in the `rates` object describes the conversion rate of one currency into the requested target currency.

| **Name**     | **Type** | **Usage**                                                                                                                                                                                                                                             |
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **rate**     | Number   | Conversion factor into the target currency. An amount in the respective currency is converted into the target currency by multiplying it with `rate` (`amount_target = amount_source × rate`). The target currency itself always has the value `1.0`. |
| **rateDate** | String   | Date of the underlying ECB rate (format `YYYY-MM-DD`). For cross rates the older of the two involved rate dates (source and target currency) is used.                                                                                                 |
| **isRecent** | Boolean  | Indicates whether the rate meets the configured recency requirements (`true`). If `false`, no sufficiently recent rate could be determined – the value is still returned but should be used with caution.                                             |

<Info>
  The base currency **EUR** is always included in the result, even if no dedicated rate record exists for it in the database. It implicitly has the rate `1.0` with the current date.
</Info>

## Methods for exchange rates

### GET exchange-rates

This endpoint retrieves a bundle of conversion rates relative to a target currency.

The target currency is passed via the mandatory parameter `target` as a three-letter ISO 4217 currency code (e.g. `EUR`, `USD`, `GBP`). The response contains a rate entry for every currency known to the system, plus the target currency itself (with rate `1.0`).

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://<your-shop>.de/admin/api/v1/exchange-rates?target=EUR
```

#### Supported parameters

| **Parameter** | **Description**                                                                                                          |
| ------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `target`      | **Mandatory.** Three-letter ISO 4217 code of the target currency to convert into. Must be exactly three characters long. |

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "target": "EUR",
    "rates": {
        "EUR": {
            "rate": 1.0,
            "rateDate": "2026-07-02",
            "isRecent": true
        },
        "GBP": {
            "rate": 1.18203,
            "rateDate": "2026-07-01",
            "isRecent": true
        },
        "USD": {
            "rate": 0.91996,
            "rateDate": "2026-07-01",
            "isRecent": true
        }
    }
}
```

In the example, `1 USD` equals roughly `0.92 EUR` and `1 GBP` roughly `1.18 EUR`. To convert an amount, multiply it by the `rate` of the source currency.

#### Error codes

| **Error**        | **Type**       | **Reason**                                                                      |
| ---------------- | -------------- | ------------------------------------------------------------------------------- |
| 401 Unauthorized |                | Not authorized: you are not logged in.                                          |
| 400 Bad Request  | "invalidValue" | The `target` parameter is missing, empty, or not exactly three characters long. |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.