Messages to other services

When a store's currencies change, Currency publishes a message so that the other Hii Retail services can follow. It uses two Pub/Sub topics:

Topic	Tells you	Received today by
cer.public.event.currencies-changed.v1	which currencies a store takes: switched on, still on, switched off	Store Data
den.public.event.denominations.v2	the coins and notes of a currency that has been switched on	Reconciliation, for counting cash

These topics are for Hii Retail services. They are not offered through External Events: a customer's own system is normally where currency changes come from, and it can read the current state from the Currency API.

The first topic's name starts with cer, after the Currency & Exchange Rates service that Currency replaced. The name and the format are kept on purpose, so that the services already subscribing keep working unchanged.

Which currencies a store takes

Topic: cer.public.event.currencies-changed.v1

One message per store, and per list

A change made for a group or for the whole company reaches many stores. Currency works out what each affected store now takes and sends messages for each store. So a subscriber never has to know the company tree.

Each message fills one of three lists and leaves the other two null:

List	Means, for this store
createdCurrencies	switched on by this change, either for the first time or again after being switched off
updatedCurrencies	still switched on after this change
deletedCurrencies	switched off by this change

So one change can give up to three messages for a store. In the picture, switching DKK on for group Sweden gives each of its stores one message with DKK as created and one with EUR and SEK as updated.

A change of default currency also arrives as an updatedCurrencies message, but the message does not say which currency is the default. Nor does it carry the number of decimals: read those from GET /currencies.

The message

{
  "tenantId": "your-tenant-id",
  "createdCurrencies": [
    { "code": "DKK", "name": "Danish Krone", "symbol": "kr", "number": "208" }
  ],
  "updatedCurrencies": null,
  "deletedCurrencies": null
}

Field
tenantId	always present
createdCurrencies, updatedCurrencies, deletedCurrencies	always present. After a change, exactly one is a list and the other two are null. When the current state is sent again, more than one can be a list.
code	always present: the ISO 4217 code, for example DKK
name, symbol, number	can be null

Message attributes:

Attribute
Tenant-Id	the tenant
Business-Unit-Id	the store the message is about
Correlation-Id	the id of the change

Receiving it correctly

🛑 The store is only in the Business-Unit-Id attribute. The message body carries the tenant and the currencies, not the store. A subscriber that reads only the body cannot tell which store a message is about.

• A message can arrive more than once. Treat createdCurrencies and updatedCurrencies as switched on for this store and deletedCurrencies as switched off for this store. Applied that way, a repeated message changes nothing.
• Messages can arrive in any order. The body carries no timestamp. If the same currency is switched off and on again for a store in quick succession, use the Pub/Sub publish time to keep the newest state, or read the store's list again from GET /api/v1/business-units/{businessUnitId}/currencies.
• Filter on the attributes. A subscription can filter on Tenant-Id or Business-Unit-Id to receive only the tenants or stores it serves.
• Ignore fields you do not recognise. The format is kept as it is for existing subscribers, and a reader that tolerates extra fields is safe either way.

Coins and notes

Topic: den.public.event.denominations.v2

When a currency is switched on, Currency also sends its coins and notes, so that cash counting knows them.

{
  "tenantId": "your-tenant-id",
  "currencyId": "SEK",
  "userId": "the user or system that made the change",
  "eventType": "Created",
  "eventDateTime": "2026-09-28T08:15:00.000Z",
  "denominations": [
    { "name": "1 kr", "value": 1 },
    { "name": "2 kr", "value": 2 }
  ]
}

All six fields are always present. eventType is Created when a currency is switched on. denominations is an empty list for a currency that has no coins and notes. See The currency list, coins and notes.

Message attributes: Tenant-Id, Event-Type (the same value as eventType) and Format-Id (json). There is no Business-Unit-Id, because coins and notes are the same in every store.

Receiving it correctly

• One message per currency and change, not per store. Switching SEK on for a group of fifty stores sends SEK's coins and notes once.
• The same list can arrive again, for example when the currency is switched on for more stores later. Treat each message as the complete list for that currency and replace what you have.
• Whether a store takes a currency comes from the currency message, not from this one.

Sending the current state again

A Hii Retail service that starts subscribing, or has lost its copy, can ask for the current state to be sent again:

POST https://currency.retailsvc.com/api/v1/currencies/initial-state

{ "tenantId": "your-tenant-id", "businessUnitId": "optional-store-id" }

Leave out businessUnitId to have every store of the tenant sent. The API answers 202. Permission: cur.initial-state.create.

Currency then sends one message per store. It lists what the store takes, in createdCurrencies or updatedCurrencies, and what has been switched off for it earlier, in deletedCurrencies, so more than one list can be filled. The coins and notes of those currencies follow.

⚠ The messages go to every subscriber of the topics, not only to the one that asked. Every subscriber must therefore cope with receiving again what it already has. A subscriber that follows the rules above does.