Sales Order Status Events

Many of the operations that are started against the aCommerce platform result in long running workflows to be executed. The Sales Order Status Events APIs allow a customer to register a webhook to receive notifications of change to the Order Status. This API is complementary to the Sales Order Status Update API and returns logically the same content. However, instead of requiring the application to poll the API for updates, much more granular events are pushed to the webhook with potentially lower latency (frequently within the same second of the event occurring). 

This API describes the schema of events that are returned when a webhook subscribes to the SALES_ORDER_STATUS_V3 stream ID. 

As described above, the events provided in this event stream are complementary to the Sales Order Status Update API. However, there are significant differences. The Update API is designed to show a complete history of the events that have occurred to an order. Over time, the orderStatus, orderDetailedStatus and shipPackage arrays have new entries added to them to reflect the historical updates of the overall Sales Order. This is necessary as there is no guarantee that the client application will call the API frequently enough to see all of these updates. However, since the event API is 'push' by nature, it can assume that it is delivering a series of these events to the consumer. As a result, the event API is designed to publish the individual entries in the orderStatus, orderDetailedStatus and shipPackage arrays as they occur. A consumer that has gone offline for a few days will miss events but they can always use the Update API to fill in whatever they missed. As such, the schema of the event API is modeled after the Update schema. Readers attempting to understand the event API are encouraged to first study the Update API to understand 'the big picture'.

On the Status Update page, we described the fact that an events found in a orderStatus array and a shipments array can occasionally be revised. Understanding this is critical for an application that is subscribing to a status WebHook. To facilitate the communication of this, each of these structures contains an eventId and eventAction field. The eventId is used to uniquely identify an individual status event.

In the normal case, new events will be published with a unique eventId and an eventAction set to 'CREATE'. For the most part, when an event is published as such, it is never changed and a WebHook consumer will only see that eventId once. However, occasionally, the event details may be revised. If this happens, an event with the same eventId as was previously published will be sent and the eventAction will be set to 'UPDATE'. This is an indication that this event has been modified from its originally published content. The proper action for the receiving application would be to overwrite the new event details on top of the previously published event. Upon very rare scenarios, this event may actually be deleted at which point, the system will publish an event with an eventAction of 'DELETE'. An example of this would be a package where the delivery driver erroneously reported that it was delivered and it fact the package was rejected by the Consumer. In this case, the correct action for the application developer would be to remove the record from any system. As always, a developer can query the Status Update API to determine the complete and current series of accurate Status Events.

Similar to the Sales Order Status Update APIs, this API set comes in 2 versions:

• Sales Order Status Events Version 3 - This is the current version of this API and it is designed to accurately reflect that a sales order may be fulfilled by zero or more shipments.
• Sales Order Status Events Version 2 - This version made assumptions that all sales orders were fulfilled with one and only one shipment. As a result, it confused statuses associated with the shipment with statuses associated with the order. And it had no facility for supporting multiple fulfillment. All developers are strongly encouraged to develop against the latest version. The version 2 of this API will be deprecated in the near future and eventually removed