Events

Business Partner publishes two events. Each carries the full current state of one partner, or of one warehouse's supply terms, every time it is created, replaced or deleted.

Topic	One event per	Listed in External Events as
bpa.public.event.business-partner-changed.v1	stored change to a partner	BPA: Business Partner Changed v1
bpa.public.event.warehouse-supply-terms-changed.v1	stored change to a warehouse's supply terms	BPA: Warehouse Supply Terms Changed v1

An event is published after the change is stored, never before, and it is built from what was stored, not from the request. What you receive is therefore exactly what a GET would return at that moment.

The partner event

The PUT example produces this event:

{
  "tenantId": "acme",
  "businessPartnerId": "V-20417",
  "status": "Active",
  "name": "Fjord Garden",
  "displayId": "20417",
  "description": "Garden tools and outdoor furniture",
  "legalName": "Fjord Garden AB",
  "vatNumber": "SE556677889901",
  "gln": "7350001234564",
  "roles": [
    { "role": "SUPPLIER", "isActive": true, "defaultLeadTimeHours": 168, "reliabilityScore": 0.95 },
    { "role": "MANUFACTURER", "isActive": true }
  ],
  "addresses": [
    {
      "addressType": "Delivery",
      "careOf": null,
      "street": "Lagervägen 4",
      "zipCode": "504 62",
      "city": "Borås",
      "county": "Västra Götaland",
      "country": "Sweden",
      "countryCode": "SE",
      "phone": "+46 33 123 45 00",
      "mobile": null,
      "email": "returns@fjordgarden.example",
      "contactPerson": "Returns desk"
    }
  ],
  "additionalProperties": [
    { "id": "paymentTerms", "name": "Payment terms", "code": "PT30", "description": null,
      "dataType": "STRING", "value": "30 days net" }
  ],
  "modifiedDatetime": "2026-10-20T08:00:01.584Z"
}

Field	Always present	Meaning
tenantId, businessPartnerId, name, status	✅	as on The business partner
roles	✅	every role the partner holds, at least one. A role missing from a newer event has been removed
addresses	✅	every address, possibly none. An address missing from a newer event has been removed
additionalProperties	✅	your own properties, possibly none
modifiedDatetime	✅	when Business Partner stored this state. Use it to order events
displayId, description, legalName, vatNumber, gln		text or null

On a SUPPLIER role, defaultLeadTimeHours and reliabilityScore are present, as null when not set. On a MANUFACTURER role they are absent.

A partner deleted with DELETE is published with status: "Deleted" and its roles and addresses still in the event. Treat the partner as deleted whatever else the event holds. A later event with another status means it has been restored.

The warehouse supply terms event

{
  "tenantId": "acme",
  "businessUnitId": "DC-JKP",
  "defaultLeadTimeHours": 48,
  "isDeleted": false,
  "modifiedDatetime": "2026-10-20T08:05:12.207Z"
}

Field	Always present	Meaning
tenantId, businessUnitId	✅	the warehouse business unit the terms belong to
isDeleted	✅	true when the terms have been deleted
modifiedDatetime	✅	when Business Partner stored this state
defaultLeadTimeHours		calendar hours, or null when not set

⚠ When isDeleted is true, ignore defaultLeadTimeHours. A deleted event still carries the last lead time that was set. The warehouse has no supply terms until an event arrives with isDeleted: false.

Attributes

Attribute	Value
Tenant-Id	the tenant
Event-Id	<businessPartnerId>:<time>, or <businessUnitId>:<time> for supply terms, where the time is when the API accepted the request. Identifies one stored change. Use it to deduplicate
Correlation-Id	the Correlation-Id of the API request that caused the change, when the request had one

There is no Business-Unit-Id attribute: partners belong to the whole tenant. Filter supply terms on the businessUnitId in the payload.

Consuming the events

Each event replaces what you hold. Every event is the whole partner, or the whole supply terms, as stored. Overwrite your copy with it; do not merge it into the previous one. A role, an address or a property that is no longer in the event has been removed.

Delivery is at-least-once: expect duplicates. Deduplicate on the Event-Id attribute. One stored change has one Event-Id, however many times it is delivered or published. Two PUTs with identical content are two changes, with two Event-Ids and two events that say the same thing; applying both is harmless.

Do not rely on arrival order. For each partner, or each warehouse, keep the event with the latest modifiedDatetime and discard any older one that arrives after it. Through External Events in particular, events for the same partner can arrive in any order.

modifiedDatetime is Hii Retail's time, not your ERP's. It is when Business Partner stored the change, which comes after the PUT was sent. It increases with every stored change to the same partner, which is what makes it safe to order by.

Handle values you do not recognise. New values may be added to the enumerations, such as role, on v1. Skip a role you do not know rather than reject the partner, and pass additionalProperties through whatever their dataType.

New optional fields arrive on this version. Adding an optional field is not a breaking change, so it is added to v1, and the published schema gains the field before any event carries it. Ignore fields you do not recognise, and if you validate against the schema, use the current published copy rather than one you saved. A new version is published only for a breaking change.

Subscribing from outside Hii Retail

Systems outside the platform receive these events through Hii Retail's External Events, where they are listed as BPA: Business Partner Changed v1 and BPA: Warehouse Supply Terms Changed v1, each with its JSON schema. Everything on this page applies unchanged to that route: the same payload, the same attributes, at-least-once delivery, and no guaranteed order.

To fill a new system with the partners that already exist, read them with GET /business-partners first, then apply events from then on. An event older than the state you read is discarded by the ordering rule above.