Exchange Rates API

The Exchange Rates API is how a customer's ERP system keeps Hii Retail's exchange rates in step with its own. The ERP sets and deletes rates, and Exchange Rates passes each change on to the stores and to the other Hii Retail services. Hii Retail apps use the same API to ask which rates a store uses.

Base URL: https://exchange-rates.retailsvc.com/api/v1

Every call needs a Hii Retail access token for the tenant. The permissions each endpoint needs are listed below, and the full reference is the Exchange Rates API reference.

The usual ERP integration

1. Your ERP is the master of the rates it sends. Whenever a rate changes in the ERP, it calls PUT for that rate, for the whole company or for one store.
2. Exchange Rates answers 202 as soon as it has accepted the change, and passes it on to the stores shortly after.
3. Read it back with GET /exchange-rates when you need to confirm what a store uses.

The calls are safe to repeat. Sending the same rate again changes nothing and sends no new message, so an ERP can send its rates again whenever it is unsure.

If the company also uses the ECB import, let the ERP send the rates the import does not create: PURCHASE and INTERCOMPANY rates, and SALES rates for currencies the ECB does not publish. A SALES rate the import creates on a level is replaced every night.

Setting a rate

To…	call
set a rate for the whole company	PUT /exchange-rates/type/{type}/currencyIdFrom/{currencyIdFrom}/currencyIdTo/{currencyIdTo}
set a rate for one store	PUT /exchange-rates/business-units/{businessUnitId}/type/{type}/currencyIdFrom/{currencyIdFrom}/currencyIdTo/{currencyIdTo}

Permission: exr.exchange-rates.create.

Path parameter
type	SALES, PURCHASE or INTERCOMPANY, in capitals. See Three types of rate.
currencyIdFrom	the currency the rate is counted in: the three-letter ISO 4217 code, in capitals, such as SEK
currencyIdTo	the currency being priced, such as EUR. It must differ from currencyIdFrom.

Request body:

{ "exchangeRate": 11.32 }

The rate is how many currencyIdFrom one currencyIdTo is worth. So this call sets 1 EUR = 11.32 SEK for the whole company:

PUT https://exchange-rates.retailsvc.com/api/v1/exchange-rates/type/SALES/currencyIdFrom/SEK/currencyIdTo/EUR

{ "exchangeRate": 11.32 }

See Reading a rate. Setting one direction is enough. The messages to other services always carry both directions, and GET /exchange-rates adds the other one when you ask for it with doCalculateMissingExchangeRates=true.

Response: 202 with the correlation id of the change:

{ "correlationId": "3f0c1f7e-4d0a-4c55-9d8e-2b8f5a1f6c21" }

Send an id of your own in the Correlation-Id header. The API uses it for the change and answers with it. Quote it if you ask Extenda to trace a change.

⚠ 202 means accepted, not yet saved. The change is saved and passed on shortly after. A rate for a store id that does not exist is accepted and then not saved, so read the rate back with GET when you set up an integration.

A rate set through the API is always kept on the level it was sent to, even when it equals the rate that level inherits. See Which rates a store uses.

A request that is not valid is answered with 400 and a message saying why: a currency code that is not a three-letter ISO 4217 code in capitals, the same currency in both places, a negative rate, or a field in the body other than exchangeRate.

Deleting a rate

To…	call
delete a rate for the whole company	DELETE /exchange-rates/type/{type}/currencyIdFrom/{currencyIdFrom}/currencyIdTo/{currencyIdTo}
delete a store's own rate	DELETE /exchange-rates/business-units/{businessUnitId}/type/{type}/currencyIdFrom/{currencyIdFrom}/currencyIdTo/{currencyIdTo}

Permission: exr.exchange-rates.delete. The answer is 202 with the correlation id, as for PUT.

• Deleting a store's own rate returns the store to the rate it inherits from its group or the company.
• Deleting the company's rate removes it from every store that uses it. Stores with a rate of their own keep theirs.
• Deleting at a store a rate it only inherits changes nothing. The rate belongs to the level above.

See Deleting a rate.

What the API does not do

Not in the API	How to do it
Set a rate for a group of stores	Use the Configuration Portal. A store uses what is set on its groups as well as what your ERP sets for it or for the company.
Switch the ECB import on or off	Use the Configuration Portal.
Set a markup	Use Hii InStore. The API reads the markups, see Reading markups.

Reading the rates a store uses

GET /exchange-rates answers with the rates each store uses, including the ones it gets from the company and its groups. Permission: exr.exchange-rates.get.

Query parameter
businessUnit	only this store
type	only this type
currencyIdFrom, currencyIdTo	only rates with these currencies
doIncludeMarkup=true	fill markup with the store's markup for each rate, in percent
doCalculateMissingExchangeRates=true	add the other direction where only one is set, as 1 ÷ rate to six decimals

GET https://exchange-rates.retailsvc.com/api/v1/exchange-rates?businessUnit=malmo&doIncludeMarkup=true

{
  "tenantId": "your-tenant-id",
  "businessUnits": [
    {
      "businessUnitId": "malmo",
      "exchangeRates": [
        { "type": "SALES", "currencyIdFrom": "SEK", "currencyIdTo": "EUR", "exchangeRate": 11.32, "markup": 2 },
        { "type": "SALES", "currencyIdFrom": "SEK", "currencyIdTo": "USD", "exchangeRate": 9.95, "markup": null }
      ]
    }
  ]
}

• The answer is always per store. A rate set for the whole company is listed under every store that uses it, so a reader never has to work out the company tree.
• markup is the percentage, not the rate with markup. It is null unless doIncludeMarkup=true is given, and also when the rate has no markup. The rate with markup is in the messages to other services.

Reading markups

GET /markups answers with the markups each store uses, with the same businessUnit, type, currencyIdFrom and currencyIdTo filters. Permission: exr.markups.get.

{
  "markups": [
    {
      "tenantId": "your-tenant-id",
      "businessUnits": [
        {
          "businessUnitId": "malmo",
          "markups": [ { "type": "SALES", "currencyIdFrom": "SEK", "currencyIdTo": "EUR", "markup": 2 } ]
        }
      ]
    }
  ]
}

See Markup for what a markup does.

Access

Role	Can
Exchange Rates configuration admin	set and delete rates, read rates and markups, and ask for the current state to be sent again

To ask for the current state to be sent again to the services that receive Exchange Rates' messages, see Sending the current state again.

Moving from the Currency & Exchange Rates API

An ERP that called the deprecated Currency & Exchange Rates API sends one call per rate instead of one call with a list of stores. The meaning of a rate does not change: the old source currency is currencyIdFrom, the old target currency is currencyIdTo, and rateValue is exchangeRate.

Currency & Exchange Rates	Exchange Rates
POST /api/v1/exchange-rates on currency-exchange-rates.retailsvc.com	PUT for the whole company or one store, on exchange-rates.retailsvc.com
DELETE /api/v1/exchange-rates	DELETE for the whole company or one store
GET /api/v1/business-units/{businessUnitId}/exchange-rates	GET /exchange-rates?businessUnit={businessUnitId}