Introduction
These sections are a guide to the Order API endpoint version 3 (v3).
Warning
This feature is currently in BETA and Voyado is actively seeking user feedback to improve its performance and functionality. We appreciate your support in this process. As a beta feature, it may undergo frequent updates and enhancements. We encourage you to check for updates regularly to take advantage of the latest improvements. While we have conducted rigorous testing, beta features could contain issues, bugs, or glitches. Be prepared for occasional disruptions, and report any issues to help us at Voyado to refine and improve the feature.
When Voyage Engage is integrated with a client’s systems, the Order module allows orders to be registered. Registered order data is stored in Engage where it can then be used by other modules, for example to view orders as part of the contact card, or to segment based on order data within the Targeting function.
It is also possible to update an order's data throughout the whole order lifecycle.
 |
Figure 1. Order overview
Other functions are the ability to get all orders for a contact, or to delete an order through the API. This means that clients can correct order data errors by themselves.
Down the road, it will be possible to use this order data in other modules in Engage, such as Automations, Reporting and Intelligence. This is in the future plan for the Order module.
Order v2 vs v3
The Order v2 API is used to trigger automations. These are mainly to send order communication to the customers, although other activities may also be included in the triggered automation. Such automations are set up to be triggered on "order" status or "payment" status.
The updated Order v3 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.
There are also differences to the format, in that v3 has a stricter format than v2. This is to more effectively extend the functionality using order data, for example in order segmentation.
Important
Order v2 and Order v3 can be used in parallel, meaning that the same order can be sent to both the Order v2 and v3 endpoints without affecting each other. In fact, until it is possible to trigger automations from Order v3 requests, Order v2 must be used if you want to trigger an automation and use it to send order communication.
Order vs Transaction
The order entity is similar to the transaction entity, but there are some important reasons why these should be represented as different entities.
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 throughout the process. The order can also be updated multiple times during the order life-cycle. Apart from the status changes there may be changes to the actual goods and services in the order. This makes it possible for a retailer to even 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 functionalities within Engage that depend on transaction amounts. For example, loyalty points being given for a purchase which in turn may result in bonus payouts or other benefits for the customer.
So an order may result in one or many transactions depending on how goods and services are delivered to the customer.
For example, an order with multiple deliveries could result in multiple transactions if the retailer so chooses.
Important
The Order and Transaction endpoints can be used in parallel. An order will only affect the order view and the segmentation on order data, while a transaction continues to affect multiple Voyado modules, such the loyalty and retention, the targeting and reporting modules.