The OMS Notification System provides order event notifications throughout the fulfillment process. Notification data is compiled automatically as the order progresses through fulfillment stages, and then sent to a JSON endpoint set up by the client. Note that these notifications are not emails sent to the consumer, but sets of data for fulfillers and clients to track the progress of the order. This system is initially configured by Kibo Professional Services.
The Notifications system is integrated with both OMS 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 OMS notifications. Read those tips before delving into the more detailed information and examples linked in the Notification Topics table below.
Important Note: Duplicates
The client’s JSON endpoint may receive duplicates of notifications on a regular basis, because OMS will resend the notification every few seconds until it receives a response such as 200 OK or times out. To avoid saturation with a large number of duplicates, configure the endpoint with duplicate prevention.
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 that are used in OMS. For more details about the data provided in each notification and examples, click the name of the topic to view that guide.
|Return Event||Return 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 Assign||This notification indicates that a shipment has been assigned to a fulfillment location.|
|Payment Transaction Error||This notification is sent after a capture or refund attempt against a transaction has failed 3 times.|
|Shipment Status||All shipment fulfillment state updates are reported by this notification.|
|Order Appeasement||This notification indicates that an order appeasement (or goodwill credit) has been initiated.|
|Order Status||Similar to Shipment Status, this reflects updates in an order’s status (including order creation).|
|Store Decline||This notification is sent when a store declines a shipment of items.|
|Order Item Modification||This is sent when the price, quantity, or tax of an order item is edited, or when an order item is canceled.|
|Order Address Change||This is sent when an order’s billing or shipping address is edited.|
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.
|eventTypeID||string||The name of the transition that prompted the notification.|
|stateFromCode||integer||The numeric code for the state that the order transitioned from.|
|stateFromName||string||The name of the state that the order transitioned from.|
|stateToCode||integer||The numeric code for the state that the order transitioned to.|
|stateToName||string||The name of the state that the order transitioned to.|
|orderID||integer||The order ID that was affected by the transition.|
|shipmentID||integer||The shipment ID that was affected by the transition.|
|orderItemID||integer||Null by default. This is only used for the cancel_item notification.|
|parentOrderID||integer||Null except in the case of a Transfer order, it will be the parent In-Store Pickup order’s orderID|
|data||object||Null by default. The data field is filled in for specific transitions that require more information with the notification.|
|scope||object||Contains the mfgID and catalogID that the order belongs to.|
An example of the default notification structure, illustrating how these parameters might be defined: