External Events

Real-time updates can be received by subscription from External Events for stock levels and transaction processing. External events is a service that provides access to events/notifications from HiiRetail Apps for External parties.

Read more about External Events

These are the events that can be subscribed to:

Event source	Version	Use it when you need
Stock Level Updates	v3	the current quantity and cost per item and stock type
Processed Transactions	v3	the full detail of every movement, and why the quantity changed

Which one do I want?

Start with Stock Level Updates. It carries the resulting quantity directly, so keeping an external view of current stock is a straight overwrite per (business unit, item, stock type) — no accumulation, no risk of drift.

Add Processed Transactions when you need the reason, not just the number: gross-profit reporting, reconciling against POS data, or an audit trail. It is a much larger contract, and it requires understanding the stock model to interpret correctly.

Consuming the events

Four properties of the delivery that an integration has to be built for:

1. Delivery is at-least-once, so duplicates are possible. The same event may be delivered more than once, for example after a transient failure. Make your handling idempotent — on Processed Transactions, transactionId identifies the movement uniquely and is a suitable deduplication key; on Stock Level Updates, applying the same level twice is harmless by construction.

2. Do not rely on receiving events in order. Order by timestamp if sequence matters to you, rather than assuming arrival order. For Stock Level Updates, the level with the newest timestamp wins for that (business unit, item, stock type).

3. Tenant and business unit are available as message attributes — Tenant-Id and Business-Unit-Id, plus Correlation-Id — as well as in the payload. Attributes are useful for routing and filtering without parsing the body.

4. Both schemas are closed. They declare additionalProperties: false, so no unexpected field will ever appear in a payload — and equally, a new field means a new event version. Handle unrecognised enum values leniently though: operationType in particular grows over time.

transactionDate or timestamp?

Processed Transactions carries both, and they answer different questions:

Field	Meaning	Use it for
transactionDate	when the movement actually happened in the source system — the moment of the sale at the POS	business reporting, day-end totals, matching against POS data
timestamp	when STP processed it	ordering the stream, and detecting how far behind you are

transactionDate can be older than one you have already received. A sale can reach STP after a stock count that came later in real time, and corrections are deliberately backdated — see Delayed transactions. A consumer that assumes the stream is sorted by business date will draw the wrong conclusions.

Quantity: delta or level?

Event	Field	Meaning
Stock Level Updates	quantity	the resulting level for that stock type
Processed Transactions	quantity	the change made by this movement
Processed Transactions	remainingStockQuantity	the resulting level after this movement

This is the most common integration mistake — see The stock model. Note also that quantities are signed: a sale is negative, and a return lands in the Returned stock type rather than adding back to SalesStock.

Stock Level Updates Schema

The Stock Level Updates event is designed to capture essential information about stock level updates, including identifiers for the tenant, business unit, and item, as well as details about the stock type, quantity, cost, and relevant timestamps. The schema ensures that all required fields are present and restricts additional properties to maintain data integrity. The stock-type.json schema provides the enumeration of possible stock types, ensuring consistent categorization of stock items.

Note on versions: subscribe to the event source v3. The schema file linked above is still named …v2.json — the event version advanced without a change to the payload shape, and the file kept its original name. The linked file is the correct schema for v3.

Properties

Always present: tenantId, businessUnitId, itemId, stockType, quantity, costAmount.

1. tenantId The tenant Id.

2. businessUnitId The id of the business unit (store).

3. itemId The id of the item.

4. stockType The type of stock. This references the stock-type.json schema which defines the possible stock types (e.g., SalesStock, InTransit, InOrder, Reserved, Returned, ReservedInOrder).

5. quantity The current quantity of the stock item for this stock type — a level, not a change.

6. costAmount The cost amount of the stock item.

7. currencyCode The 3-letter currency code for the transaction.

8. averageCostAmount The average cost amount of the stock item.

9. timestamp The timestamp of the stock level update in UTC timezone.

Processed Transaction Schema

The stp.public.output.processed-transactions.v3 schema is designed to capture comprehensive information about processed stock transactions. It includes identifiers for the transaction, tenant, business unit, and item, as well as details about the stock type, quantities, costs, and relevant timestamps. The schema also includes fields for document references, correlation identifiers, stock handling types and methods, and additional properties. This ensures that all necessary information is captured and structured consistently for processed transactions in a retail system.

Always present: transactionId, tenantId, businessUnitId, itemId, stockType, transactionDate, quantity, costAmount, documentType, correlationId, stockHandlingTypeId, stockHandlingMethodId, useAverageWeightedCostPrice, isStructuredItem, operationType. Everything else is optional and may be absent depending on the operation and the item.

Properties

1. transactionId Unique id for the transaction. Suitable as a deduplication key.

2. tenantId The tenant Id.

3. businessUnitId The id of the business unit (store).

4. itemId The id of the item.

5. stockType The type of stock. This references the stock-type.json schema which defines the possible stock types (e.g., SalesStock, InTransit, InOrder, Reserved, Returned, ReservedInOrder).

6. transactionDate The date of the transaction in UTC timezone. This is the actual timestamp for when the transaction was done in any system, e.g., POS, not when processed.

7. quantity The quantity by which the targeted entity is affected — a change, signed. Expect to have 2 digits after the point precision.

8. originalQuantity Quantity originally used for the document before processing. Expect to have 2 digits after the point precision.

9. costAmount The cost amount by which the targeted entity is affected. Expect to have 3 digits after the point precision.

10. salesAmount The sales price if sold. Expect to have 3 digits after the point precision.

11. currencyCode 3 letter currency code for the transaction.

12. reasonCode Reason code for the transaction.

13. comment Additional comments for the transaction.

14. documentType The type of document that produced this transaction.

15. documentId The id of the document that produced this transaction. For a sale this is the POS transaction id, which is what links a stock movement back to its receipt.

16. documentLineId The id of the document line that produced this transaction.

17. businessPartnerId Identifier of the business partner attached to the affected StockItem.

18. batchNumber The Batch/Lot number attached to the affected StockItem.

19. serialNumber The serial number attached to the affected StockItem.

20. correlationId A unique identifier used to correlate all transactions processed by a single message.

21. linkIdExternal An optional unique identifier specified by the sender. Could be used to link several messages from the sender.

22. linkIdRelated A unique identifier used to correlate the related transactions (one transaction causing several transactions during processing). Group on this to reassemble one business operation — see Multiple transactions.

23. linkIdStructure A unique identifier used to correlate transactions to the same structured item — see Structured items.

24. linkIdDelayed A unique identifier used to correlate stock count transactions with delayed transactions (arrives after the stock count is processed, but is done before the stock count) — see Delayed transactions.

25. sourceType Indicates the type of device performing the sale, e.g., Mobile Access, RS POS, Extenda POS, etc.

26. sourceId Indicates the id of the device performing the transaction.

27. stockHandlingTypeId

    • $ref: stock-handling-type.json Indicates the stock handling type at the time of processing the transaction, e.g., NO_STOCK_HANDLING, DO_STOCK_HANDLING, DO_CONSIGNMENT_STOCK_HANDLING.

28. stockHandlingMethodId

    • $ref: stock-handling-method.json Indicates the stock handling method at the time of processing the transaction, e.g., FIFO, FEFO, LIFO.

29. useAverageWeightedCostPrice Indicates whether an average weighted cost price was used when resolving the cost of this movement, rather than the batch's own cost or the item's purchase price. See Cost calculations.

30. isStructuredItem True if the item is a master product (containing child products) at the time of processing the transaction.

31. createdBy Identity of the user triggering the transaction.

32. bestBeforeDate Best before date of the stock item.

33. expirationDate Expiration date of the stock item.

34. purchasePrice Purchase price of the stock item.

35. operationType The type of operation performed in the transaction. See Operations for what each one does to the stock. Referenced from the transaction-operation-type.json schema; treat it as an open enumeration and handle unrecognised values, since new operations are added over time.

36. additionalProperties Additional properties related to the transaction.

37. remainingStockQuantity A snapshot of stock quantity for the processed stock type after this transaction is processed — a level, not a change.

38. remainingCostAmount A snapshot of stock cost amount after this transaction is processed.

39. timestamp Timestamp of when the transaction was processed. Use this to order the stream.

Stock Type Schema (stock-type.json)

The stock-type.json schema defines the possible types of stock in a retail system. It is used to categorize stock items based on their status or location within the supply chain. See The stock model for what each one means to the business.

Properties

• type: string
• enum:
  • SalesStock: Stock available for sale.
  • InTransit: Stock that is currently being transported.
  • InOrder: Stock that has been ordered but not yet received.
  • Reserved: Stock that is reserved for a specific purpose or customer.
  • Returned: Stock that has been returned by customers.
  • ReservedInOrder: Stock that is reserved and also in order.

---

Return