Sales Order Status Updates

Many of the operations that are started against the aCommerce platform result in long running workflows to be executed. The Sales Order Status updates APIs allow a customer to register to receive notification using mechanisms that are appropriate to them. This rich set of methods for notification can be summarized as such:

• WebHooks exposed by the channel or partner that aCommerce will call when an individual order's status has changed
• This API that allows a channel or partner system to programmatically ask for order status changes
• email delivery of CSV files containing a batch of orders
• FTP delivery of CSV files containing a batch of orders

The recommended mechanism for understanding the status is a webhook as it gives the following advantages:

• The latency of notification is the lowest possible. For example, when aCommerce receives notification of an update from a shipper that a package has been delivered, we can schedule the call back to your web hook very quickly (frequently in real time).
• Use of this API creates a possibility for the caller to violate rate limits. A caller may run into rate limiting if they are trying to poll repeatedly for an update on the same order ID. Conversely, WebHook calls are rate limited by the receiving system and the aCommerce infrastructure will honor notifications from the webhook that we are sending too fast and back off.

The status API only supports the GET verb and a partner or channel will need to use other APIs to modify an order that they have place. This API allows the partner to retrieve Order status in a manner that is designed to be very efficient for that entity reducing workload on their own systems. In general, this API allows the use of TIME as a key value for constraining the results coming back. And it allows that customer to easily utilize a polling construct to periodically get updates on orders whose status has changed.

It is important to recognize that occasionally, some Status History events can change content over time. This is due to the details associated with a status event being modified after it was published. Most of these cases are due to erroneous data entry when the event was first reported. To facilitate detection of a change to a previously published status, aCommerce has included a new field: eventId, which is used to uniquely identify an individual event. This key for the status event is globally unique.

In the normal case, new events will show up with a unique eventId. For the most part, when an event is published as such, it is never changed. However, occasionally, the event details may be revised. If this happens, the eventId will remain the same, so that you are sure we are referring to the same event. Upon very rare scenarios, this event may actually be deleted at which point, the system will no longer show the event with that specific eventId. An example of this would be a package where the driver erroneously reported that it was delivered and it fact the package was rejected by the Consumer. Note that in any individual request to the API, a status history array will only show unique eventIds. In other words, only the latest state of an individual eventId will be retained.

To access the aCommerce Sales Order Status REST API, you must establish a secure Authentication. Additionally, this API supports pagination with a maximum of 100 records returned per request.