Messages to other services

When a country's tax rules change, Tax Rules publishes a message so that the other Hii Retail services can follow.

Topic	Tells you	Received today by
tax.public.event.tax-rules.v2	every tax region, taxable group, rule and rate of one country	Business Unit Management, Store Data

The topic is for Hii Retail services. It is not offered through External Events. A customer's own system reads the same rules from the Tax Rules API, which also resolves the company's aliases for it.

When a message is sent

• When a change is released. One message for each country that changed. When the global list of taxable groups changes, one message for every country. See How rates change.
• When the rules are sent again on request. The same message, for some countries or all, and possibly aimed at one service or one tenant. See Attributes.

Nothing is sent on the day a rate starts to apply. The rate was in the message when it was released. See A rate announced in advance is sent before it applies.

What a message holds

One message is one whole country, with nothing left out: every region, every rule and every rate, old, current and announced.

Field	Holds	Always there
version	the version of the file format, 1.0	✓
countryCode	the country, such as FI	✓
taxRegions	the country's regions, each with id, name and the region's own taxableGroups, and the tax-exempt twins	✓
taxRules	each rule with id, name, taxRegionId, taxableGroupId, optional fiscalTaxGroupId, and rates: each with id, rate, validFrom and optional status	✓
taxableGroups	the global list of taxable groups, the same in every message, with every tenant's aliases
exemptions	the country's exemptions, each with id, name, taxRegionId and rates (id, validFrom, optional status)

validFrom is a date, such as 2026-01-01. The message follows the TaxRules JSON schema, which allows no fields beyond those above.

Attributes

Attribute	Means
Country-Code	the country in the message, such as FI
Tax-Timestamp	when this country's rules last changed, in ISO 8601 UTC, such as 2025-12-04T04:14:53Z. It is not the time the message was sent: a resend of unchanged rules carries the same value as the release that produced them.
Content-Type	application/json
Correlation-Id	the same on every message of one release or resend
User-Id	SYSTEM for a release, otherwise the user who asked for a resend
Do-Fanout	false on a release. A resend can set it to true for a receiver that passes the rules on to others.
Consumer	on a resend aimed at one service only: that service's name. Missing on a release.
Tenant-Id	on a resend for one tenant only: that tenant. Missing on a release.

A subscription takes a message when Consumer is missing or is its own name. Filter on it, with attributes.Consumer = "<your service>" OR NOT attributes:Consumer, so that a resend aimed at another service does not reach you.

Receiving the message

• Replace, do not merge. A message is the complete state of its country. Replace everything you hold for that country with it. A region, rule or rate that is no longer in the message is gone.
• Ignore a message that is older than the rules you hold. Keep the Tax-Timestamp of the rules you hold for each country. Skip a message whose Tax-Timestamp is older; apply one whose Tax-Timestamp is the same or newer.
• Keep every rate with its date, and choose by the date of the sale. Do not keep only the newest rate. See Current rate or the whole list for the rule.
• Duplicates are possible. Delivery is at least once. A duplicate has the same Tax-Timestamp and the same rules, so applying it again changes nothing.
• Arrival order is not guaranteed. Two messages for the same country come from two separate releases, which are normally days apart, so they arrive in order. They can swap when an older message is still being redelivered after a newer one has arrived, for example because your service was unavailable or failed while the first was delivered. Replacing with the older message would bring back the earlier rules, which is why the Tax-Timestamp check above is needed.
• Aliases are not applied for you. taxRules uses the global group ids. A service that needs a tenant's alias finds it in taxableGroups[].aliases: the alias for the tenant and country under countryCodeAliases if there is one, otherwise the tenant's alias.
• New values arrive without a new version. A new country, region, taxable group or exemption is just more data. Handle ids you have not seen before. A new field, on the other hand, comes with a new version of the topic.