Skip to main content

Vendor currencies and rates

This guide explains how to read vendor currencies, add new currencies, and update conversion rates.

These endpoints accept any authentication (user JWT or app credentials). Write operations require the scopes listed below.

What are “rates”?​

Rates are conversion factors to the vendor’s base currency.

Example:

  • Base currency: USD
  • EUR rate: 1.2 means (1 EUR = 1.2 USD) in the system.

High-level flow​

Read currencies and rates (ANYAUTH)​

List all currencies (with rates)​

  • Method: GET
  • Path: /api/v1/vendor/currencies
  • Auth: Any (no scope required).
curl -X GET "https://your-api/api/v1/vendor/currencies" \
  -H "Authorization: Bearer <token>"

Get one currency​

  • Method: GET
  • Path: /api/v1/vendor/currencies/{currency}
  • Auth: Any.
curl -X GET "https://your-api/api/v1/vendor/currencies/eur" \
  -H "Authorization: Bearer <token>"

Read rates only (ANYAUTH)​

All rates​

  • Method: GET
  • Path: /api/v1/vendor/currencies/rates
  • Auth: Any.
curl -X GET "https://your-api/api/v1/vendor/currencies/rates" \
  -H "Authorization: Bearer <token>"

One rate (with history)​

  • Method: GET
  • Path: /api/v1/vendor/currencies/rates/{currencyCode}
  • Auth: Any.
curl -X GET "https://your-api/api/v1/vendor/currencies/rates/eur" \
  -H "Authorization: Bearer <token>"

Add new currencies (ANYAUTH + scope)​

  • Method: POST
  • Path: /api/v1/vendor/currencies
  • Auth: Any, with VENDOR_CURRENCIES_ADD scope.

Request body​

{
  "currencies": [
    {
      "currency": "eur",
      "symbol": "€",
      "fullName": "Euro",
      "shortName": "EUR",
      "roundedTo": 0.01
    }
  ]
}

Field rules:

  • currency: 1–10 characters (e.g. eur, usd)
  • symbol: 1–10 characters
  • fullName: 1–100 characters
  • shortName: 1–50 characters
  • roundedTo: one of 0.01, 0.1, 1, 10, 100

curl​

curl -X POST "https://your-api/api/v1/vendor/currencies" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "currencies": [
      {
        "currency": "eur",
        "symbol": "€",
        "fullName": "Euro",
        "shortName": "EUR",
        "roundedTo": 0.01
      }
    ]
  }'

Update conversion rates (ANYAUTH + scope)​

All rate update endpoints require VENDOR_CURRENCIES_RATES_UPDATE scope (user or app).

Bulk update rates​

  • Method: POST
  • Path: /api/v1/vendor/currencies/rates
  • Auth: Any, with VENDOR_CURRENCIES_RATES_UPDATE.
curl -X POST "https://your-api/api/v1/vendor/currencies/rates" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "currencies": {
      "rates": {
        "eur": 1.2,
        "usd": 1.0,
        "gbp": 1.35
      }
    },
    "changedBy": "rate-sync-job"
  }'

Update a single rate​

  • Method: PATCH
  • Path: /api/v1/vendor/currencies/{currencyCode}/rate
  • Auth: Any, with VENDOR_CURRENCIES_RATES_UPDATE.
curl -X PATCH "https://your-api/api/v1/vendor/currencies/eur/rate" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "conversionToBaseCurrency": 1.15,
    "changedBy": "admin@example.com"
  }'

Best practices​

  • Update rates from a single, trusted source (scheduled job).
  • Keep your own audit context in changedBy (job name, admin email, correlation id).
  • Validate currencies exist before setting rates (create currency first, then set rate).