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 all orders sent to the endpoint, which was not done before. This expands the usefulness greatly, allowing orders to now be used in segmentation and in other areas of Engage.
Other functions available are the ability to fetch all orders for a contact, or to delete an order through the API. This means that 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 v2 compared to v3
This is a quick overview of the differences between the Orders v3 and Orders v2 APIs:
Feature | Orders v2 | Orders v3 |
|---|---|---|
Triggers transactional communication | YES | YES |
Uses standardized data model | NO | YES |
Stores order object in database | NO | YES |
Filters out customers with ongoing orders | NO | YES |
Fetches order data through Engage API | NO | YES |
Requires entire payload in request to trigger email send-out | YES | NO |
Allows viewing info on ongoing order for a contact in Engage UI | NO | YES |
Permits order data to be used in reporting and intelligence | NO | YES (coming) |
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, except for the case where embedded order actions are used.
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:
Embedded order actions
When you change the status of an order or its delivery details via the API, you will receive a job ID in the response. This ID can then be used this to manually poll the system to see when the change you requested had actually been processed so that any subsequent actions, such as sending confirmation emails, can be triggered via the /action endpoint.
Enbedded order actions provide a neater way of doing this. When you change the status of an order or its delivery details, you now have the option of sending your “instructions” about what is to be done after the change is processed as an order action parameter in the payload. This allows follow-up activities such as sending confirmation email to be triggered automatically with no polling needed.
Important
Embedded order actions are an optional complement to the /action endpoint for triggering automations and not a replacement. If there are any issues with processing an order action (such as a contact not being found), the embedded order action will be discarded. You should consider having some form of counteraction in place in case this happens.