Event Notifications Overview


This documentation is for translated notifications and intended only for some implementations who have upgraded from a previous version of Order Management. Verify whether your implementation uses translated APIs before continuing, as you will receive different data if your tenant is not configured to use these. If your implementation is not configured to do so, then refer to the standard Notifications documentation instead.

For clients upgrading from a previous version of OMS to the Unified Commerce Platform, there is no significant change to the notifications system from the client side. Notification data is still compiled automatically as the order progresses through fulfillment stages, and then sent to a JSON endpoint set up by the client. The Unified Commerce translation layer ensures that all data fields match what the client is already expecting to receive.

The Notifications system is integrated with both APIs and interfaces. There are not separate notification types for events that happen in the interface and the APIs; rather, they are triggered by any appropriate event regardless of where it happens. However, some notification variants may only apply to a specific fulfillment type and thus are dependent on what the interface supports. For example, when a client is using the retailer interface that doesn’t allow In-Store Pick Up fulfillment but does allow Ship to Store (Automated), then STSA-specific notifications will be triggered when a retailer puts an order through fulfillment.

This overview lists important things to remember about JSON endpoints, topic buckets, and the default structure of notifications. Read those tips before delving into the more detailed information and examples linked in the Notification Topics table below.

Setting Up Notifications

These translated notifications must be set up by Kibo Engineering first, so contact your Project Team or Kibo Support to request their assistance.

Endpoint Configuration Notes

The platform expects a 200 OK success response to be returned from the receiving JSON endpoint within 45 seconds of sending the notification. If no success response is received during that time or if an HTTP status error message is received, the notification will be placed in a queue to be resent every minute or so (the actual timing will vary based on the size of the queue). The notification will continue to be resent until either the success response is received or the notification expires after 14 days.

Due to this process, the JSON endpoint may sometimes receive duplicates of notifications. To avoid saturation with a large number of duplicates, it is recommended to configure the endpoint with duplicate prevention.

Additionally, this means that it is possible for notifications to sometimes be received out of order. For example, if the Ready Order Notification failed and was placed in the retry queue, but the subsequent fulfillment and Package Complete notifications are successfully sent on their first try, then Ready Order may be received last. Thus, it is also advised to configure the endpoint to be capable of receiving out-of-order notifications to avoid any problems that may be caused by expecting notifications in a strict order.

Notification Topics

Notifications are organized by topics, which are buckets of one or more notifications that are all associated with a particular process such as returns or shipments. The following table provides a quick reference to the basic notifications topics. For more details about the data provided in each notification and examples, click the name of the topic to view that guide.

Return EventReturn event notifications are sent for the creation, modification, and removal of returns. They will be triggered when a return is created, accepted, declined (or deleted), re-opened, and cleared.
Shipment AssignThis notification indicates that a shipment has been assigned to a fulfillment location.
Payment Transaction ErrorThis notification is sent after a capture or refund attempt against a transaction has failed 3 times.
Shipment StatusAll shipment fulfillment state updates are reported by this notification.
Order AppeasementThis notification indicates that an order appeasement (or goodwill credit) has been initiated.
Order StatusSimilar to Shipment Status, this reflects updates in an order’s status (including order creation).
Store DeclineThis notification is sent when a store declines a shipment of items.
Order Item ModificationThis is sent when the price, quantity, or tax of an order item is edited, or when an order item is canceled.

Default Structure

Many notifications use the default structure, unless otherwise noted for a particular use case. The fields of this structure are described in the below table.

eventTypeIDstringThe name of the transition that prompted the notification.
stateFromCodeintegerThe numeric code for the state that the order transitioned from.
stateFromNamestringThe name of the state that the order transitioned from.
stateToCodeintegerThe numeric code for the state that the order transitioned to.
stateToNamestringThe name of the state that the order transitioned to.
orderIDintegerThe order ID that was affected by the transition.
shipmentIDintegerThe shipment ID that was affected by the transition.
orderItemIDintegerNull by default. This is only used for the cancel_item notification.
parentOrderIDintegerNull except in the case of a Transfer order, it will be the parent In-Store Pickup order’s orderID
dataobjectNull by default. The data field is filled in for specific transitions that require more information with the notification.
scopeobjectContains the mfgID and catalogID that the order belongs to.

Notification Example

The below is an example of the default notification structure, illustrating how these parameters might be defined:

    "eventTypeID": "ReturnAcceptedByFulfillerForShipper",
    "stateFromCode": 1100,
    "stateFromName": "return_initiated",
    "stateToCode": 1300,
    "stateToName": "return_accepted_by_fulfiller_for_shipper",
    "orderID": 123456,
    "shipmentID": 654321,
    "orderItemID": null,
    "parentOrderID": null,
    "data": null,
    "scope": {
        "mfgID": "1111",
        "catalogID": "0"