Introduction
When Voyado Engage is integrated with a client’s systems, the Orders module allows orders to be registered. The latest version of the /orders API stores the orders sent to the endpoint. This expands the usefulness greatly, allowing orders to now be used in segmentation and other areas of Engage.
Other functions are the ability to get all orders for a contact, or delete an order through the API. This means clients can correct order data errors by themselves. In fact it's possible to update an order's data throughout its entire life-cycle.
Orders vs Transactions
The order entity is similar to the transaction entity, but there are some vital differences.
An order represents the goods and services being purchased (or returned) at the time of the actual order, online or in-store. This data can change and the order can be updated multiple times during its life-cycle. Apart from the status changes, there may be changes to the actual goods and services in the order. So a retailer can add, update or remove order line items throughout the order life-cycle.
A transaction on the other hand represents an actual exchange of goods or services between the retailer and the customer. A transaction, once registered, is never changed, as there are other processes within Engage that depend on transaction data. For example, the loyalty points being given for a purchase, which in turn may result in bonus payouts or other benefits for the customer.
Important
An order may result in many transactions, depending on how the goods and services are delivered, and if any are returned. For example, an order with multiple deliveries could result in multiple transactions.
Orders and transaction also use different endpoints:
The endpoint used for registering orders is /api/v3/orders
The endpoint used for registering transactions is /api/v3/receipts
Important
Both of these endpoints should be used in parallel. An order will only affect the order view and the segmentation of order data (and the sent communication using the /actions endpoint) whereas a transaction affects multiple Engage modules, such the loyalty, targeting and reporting, as it did in v2.
Orders v3 overview
The orders v3 API endpoints can be divided into two types, administration and action.
The administration part is for creating, reading and updating orders. All changes are processed and moved into segmentation (currently available in “Filter tool”). In this group are all orders endpoints apart from /action.
Important
No communication is triggered when using the administration endpoints.
The action part is used when the client wants to trigger some action on an order that has been processed in Engage. For now, this basically means triggering automations, but there is a plan to add more functionality.
To make sure the system uses the correct data when communicating, the client has to specify a VersionTag when triggering actions. This VersionTag is returned when a change to an order has been processed. It is available either via the /jobstatus endpoint when creating or updating the order, or from /orders endpoint. Here you can see the data flow for orders and order communication:
