Currency API

The Currency API is how a customer's ERP system keeps Hii Retail's currencies in step with its own. The ERP switches currencies on and off, and Currency passes each change on to the stores and to the other Hii Retail services. Hii Retail apps use the same API to ask which currencies a store takes.

Base URL: https://currency.retailsvc.com/api/v1

Every call needs a Hii Retail access token for the tenant. The permissions each endpoint needs are listed below.

The usual ERP integration

1. Your ERP is the master of which currencies each store takes. Whenever that changes in the ERP, it calls PUT with ENABLE or DISABLE, for the whole company or for one store.
2. Currency answers 200 as soon as the change is saved, and passes it on to the stores shortly after.
3. Read it back with GET /business-units/{businessUnitId}/currencies when you need to confirm what a store takes.

The calls are safe to repeat. Switching on a currency that is already on, or off one that is not on, answers 200 and changes nothing, so an ERP can send its setup again whenever it is unsure.

Switching a currency on or off

To…	call
switch a currency on or off for the whole company	PUT /currencies/{currencyId}
switch a currency on or off for one store	PUT /business-units/{businessUnitId}/currencies/{currencyId}

Permission: cur.currency.create.

{currencyId} is the three-letter code in capitals, exactly as in the currency list: SEK, not sek. Any other code, including a lower-case one, is rejected with 404.

Request body:

{ "operation": "ENABLE" }

operation	Effect
ENABLE	Switches the currency on at that level. Every store below takes it. This is the default if operation is left out.
DISABLE	Switches the currency off at that level.

Response: 200 with the correlation id of the change:

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

Send your own id in the Correlation-Id header to have it used, and returned, instead of a generated one. Quote it if you ask Extenda to trace a change.

If the change cannot be saved, the API answers with the error status and does not answer 200.

What switching off does depends on the level, as described in Switching a currency off:

• DISABLE for the whole company removes the currency from every store that takes it from the company.
• DISABLE for one store removes it from that store only, even when the store gets it from the company or a group. The other stores keep it.

What the API does not do

Not in the API	How to do it
Switch a currency on or off for a group of stores	Use the Configuration Portal. A store takes what is set on its groups as well as what your ERP sets for it or for the company.
Choose the default currency	Use the Configuration Portal. A currency switched on through the API is not the default.

Reading which currencies are switched on

To get…	call	Permission
everything one store takes, including what it gets from the company and its groups	GET /business-units/{businessUnitId}/currencies	cur.currency.get
what is switched on for the whole company	GET /currencies-enabled	cur.currency.get

GET /business-units/{businessUnitId}/currencies is the one to use when the question is "what does this store take?" It answers with the store's full list:

{
  "currencies": [
    { "code": "EUR", "name": "Euro", "number": "978", "symbol": "€", "numberOfDecimals": 2 },
    { "code": "NOK", "name": "Norwegian Krone", "number": "578", "symbol": "kr", "numberOfDecimals": 2 }
  ]
}

GET /currencies-enabled returns only what is set for the whole company, as a list of currencies in the same shape. It does not include what is set on groups or stores.

⚠ Neither answer says which currency is the default. The default is chosen in the Configuration Portal, and Hii Retail apps read it from the company's configuration.

Reading the currency list

To get…	call	Permission
all 179 currencies	GET /currencies	cur.currency.get
the coins and notes of one currency	GET /currencies/{currencyId}/denominations	cur.denominations.get

GET /currencies returns the same currency fields as above. GET /currencies/{currencyId}/denominations returns the coins and notes, lowest value first, and an empty list for a currency that has none:

[
  { "name": "1 kr", "value": 1 },
  { "name": "5 kr", "value": 5 }
]

See The currency list, coins and notes for what the fields mean.

Access

Role	Can
Currencies Admin	switch currencies on and off, read everything, and ask for the current state to be sent again
Currencies for a tenant	read the currency list and which currencies are switched on. It does not include the coins and notes.

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