← All articles

Manage currencies and exchange rates

Every Sage 50 company has a home currency (for example CAD). Foreign currencies such as USD are configured through the Currencies API, and dated exchange rates are managed through the Exchange Rates API. Together they let you post invoices, purchases, and journal entries in a foreign currency.

The home currency already exists in Sage and cannot be created, modified, or deleted through the API. Use POST /api/currencies only to add foreign currencies.

Prerequisites

Before working with currencies, make sure you have:

Authentication

Pass your API key in the x-api-key request header:

x-api-key: YOUR_API_KEY

Endpoints

GET    /api/currencies
POST   /api/currencies
GET    /api/currencies/{id}
PUT    /api/currencies/{id}
DELETE /api/currencies/{id}
GET    /api/currencies/{code}

GET    /api/exchange-rates?currencyId={id}
POST   /api/exchange-rates
PUT    /api/exchange-rates
DELETE /api/exchange-rates?currencyId={id}&date={date}
GET    /api/exchange-rates/current?currencyId={id}
GET    /api/exchange-rates/exact?currencyId={id}&date={date}

List currencies

Use GET /api/currencies to return every currency configured in Sage, including the home currency. This is the best starting point when you need a currencyId for exchange rate calls or want to confirm which currencies are already set up.

[
  {
    "id": 1,
    "code": "CAD",
    "description": "Canadian Dollar",
    "isHomeCurrency": true,
    "symbol": "$",
    "used": true,
    "currentExchangeRate": 1.0
  },
  {
    "id": 2,
    "code": "USD",
    "description": "US Dollar",
    "isHomeCurrency": false,
    "symbol": "$",
    "used": true,
    "currentExchangeRate": 1.48
  }
]

isHomeCurrency marks the company’s base currency. used is true when the currency is referenced in transactions. currentExchangeRate appears on foreign currencies and reflects the rate in effect today relative to the home currency. Currency ids differ per company.

Create a foreign currency

Use POST /api/currencies to add a foreign currency. The home currency cannot be created through this endpoint.

Field Required? What happens if omitted
code Yes Request is rejected. The code must be unique (e.g. USD)
description Yes Request is rejected
symbol Yes Request is rejected
decimalPlaces No Sage uses its default decimal precision for the currency

Request body:

{
  "code": "EUR",
  "description": "Euro",
  "symbol": "EUR",
  "decimalPlaces": 2
}

A successful request returns 201 Created with the new currency, including its Sage id:

{
  "id": 3,
  "code": "EUR",
  "description": "Euro",
  "isHomeCurrency": false,
  "symbol": "EUR",
  "used": false
}

currentExchangeRate is omitted until an exchange rate exists for the currency.

Look up a currency

Look up a currency by Sage internal id:

GET /api/currencies/2

Or by currency code when you already know it:

GET /api/currencies/USD

Both return a single SageCurrencyDto object. Use the code lookup when integrating with external systems that store ISO currency codes. Use the id lookup when you already have the value from GET /api/currencies or a create response.

Update and delete a currency

Update a foreign currency with PUT /api/currencies/{id}. Send the same fields as create. The home currency cannot be modified. Changing the code is rejected if the new code is already in use.

{
  "code": "USD",
  "description": "United States Dollar",
  "symbol": "$",
  "decimalPlaces": 2
}

A successful update returns 204 No Content.

Delete a foreign currency with DELETE /api/currencies/{id}. The home currency cannot be deleted. If the currency is referenced in transactions (used: true), Sage returns 400 Bad Request with a message such as Currency 2 is in use and cannot be deleted.

Exchange rates

Exchange rates apply only to foreign currencies, not the home currency. Each rate is dated and expressed relative to the company’s home currency. For example, a rate of 1.35 on USD means 1 USD equals 1.35 CAD when CAD is the home currency.

List rate history

Use GET /api/exchange-rates?currencyId=2 to return all recorded rates for a foreign currency, ordered by date.

[
  {
    "currencyId": 2,
    "date": "2025-03-01T00:00:00",
    "rate": 1.34
  },
  {
    "currencyId": 2,
    "date": "2025-03-15T00:00:00",
    "rate": 1.35
  }
]

Set a rate

Use POST /api/exchange-rates to create or replace the rate for a specific date. PUT /api/exchange-rates behaves the same way. The rate must be greater than zero. If a rate already exists on that date, it is overwritten.

Field Required? What happens if omitted
currencyId Yes Request is rejected. Use the foreign currency’s internal id
date Yes Request is rejected
rate Yes Request is rejected. Must be greater than zero

Request body:

{
  "currencyId": 2,
  "date": "2025-03-15T00:00:00",
  "rate": 1.35
}

A successful request returns 200 OK:

{
  "currencyId": 2,
  "date": "2025-03-15T00:00:00",
  "rate": 1.35
}

Look up a rate

Two endpoints retrieve a single rate, but they behave differently:

Endpoint Behavior
GET /api/exchange-rates/current?currencyId=2&asOf=2025-03-20T00:00:00 Returns the rate in effect on the given date. If no rate exists exactly on that date, Sage returns the most recent rate on or before the date. Omit asOf to use today.
GET /api/exchange-rates/exact?currencyId=2&date=2025-03-15T00:00:00 Returns the rate recorded exactly on that date. Returns 404 when no rate exists on that exact date.

Use /current when you need the rate Sage would apply on a transaction date. Use /exact when you need to confirm whether a rate was set on a specific day.

Delete a rate

Use DELETE /api/exchange-rates?currencyId=2&date=2025-03-15T00:00:00 to remove the rate recorded on that date. A successful delete returns 204 No Content. Returns 404 when no rate exists on that date.

Use currencies on transactions

Once a foreign currency and its exchange rate are configured, you can post transactions in that currency. Sales invoices, purchase invoices, and general journal entries accept optional currencyCode and exchangeRate fields on the request header.

If you omit both fields, Sage uses the company home currency. When posting in a foreign currency, send both currencyCode and exchangeRate.

See the general journal article for a full foreign-currency posting example with currencyCode: "USD" and exchangeRate: 1.35.

Customers and vendors also store a currencyCode. Use GET /api/customers or GET /api/vendors to see which currency each record uses.

cURL examples

List all currencies:

curl "/api/currencies" \
  -H "x-api-key: YOUR_API_KEY"

Create a foreign currency:

curl -X POST "/api/currencies" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "code": "EUR",
    "description": "Euro",
    "symbol": "EUR",
    "decimalPlaces": 2
  }'

Set an exchange rate:

curl -X POST "/api/exchange-rates" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "currencyId": 2,
    "date": "2025-03-15T00:00:00",
    "rate": 1.35
  }'

Get the current rate for a date:

curl "/api/exchange-rates/current?currencyId=2&asOf=2025-03-20T00:00:00" \
  -H "x-api-key: YOUR_API_KEY"

Error response

If the request is invalid or Sage rejects the operation, the API returns an error with a ProblemDetails body. Common cases:

Duplicate currency code on create:

{
  "title": "Bad request",
  "status": 400,
  "detail": "Currency code USD already exists",
  "code": "400",
  "requestId": "632969a5-d81a-418c-a098-116184f03b3e"
}

Currency in use on delete:

{
  "title": "Bad request",
  "status": 400,
  "detail": "Currency 2 is in use and cannot be deleted",
  "code": "400",
  "requestId": "1d508efd-e91b-429e-a973-4d63fa9509d4"
}

Home currency cannot be modified or deleted:

{
  "title": "Bad request",
  "status": 400,
  "detail": "Home currency cannot be deleted",
  "code": "400",
  "requestId": "3816dc8e-17f3-4131-9cc9-96fba880e181"
}

Exchange rate must be greater than zero:

{
  "title": "Bad request",
  "status": 400,
  "detail": "Exchange rate must be greater than zero",
  "code": "400",
  "requestId": "7d30ae67-0960-4423-bf13-30a93ec59355"
}

Exchange rate not found on exact lookup:

{
  "title": "Not found",
  "status": 404,
  "detail": "Exchange rate for currency 2 on 2025-04-01 not found",
  "code": "404",
  "requestId": "a2ff44ea-4bdd-46eb-a382-ec9cf396e428"
}

Other common causes include attempting to modify the home currency (Home currency cannot be modified), and using a currencyId that does not exist.

Next steps