Skip to main content
This guide covers the step-by-step actions you’ll take when integrating Voyado Engage to your system, as well as the basic concepts.
There are many ways to integrate your systems with Engage. Here you’ll see the integration best practice that Voyado recommends.
This is a high-level overview so data fields and JSON specifications will not be covered in any detail. If you need that, consult your Swagger page, or the other relevant parts of this documentation. This guide assumes you’ll be integrating your system to Engage from scratch. Engage also has prebuilt integrations (accelerators) supporting many third-party systems, enabling a faster and easier integration.

List of supported third-party integrations

​
1 - Initial configuration

Some initial configuration is needed in Engage before you can start integrating your data and flows. Make sure that these basic steps are done before you continue.
  • Confirm that stores are created and configured in Engage. This is needed since contact data usually has a reference to the store where the contact signed up.
  • Confirm that contact attributes are set up. This involves configuration of the contact identification key and the mandatory unique fields for contacts in Engage.
  • You need an article register in your Engage environment, so you can segment contacts based on article data attributes like category and brand.
Connecting a system to Engage is always synchronous. So when the Engage API is called, your workflow needs to wait for a response before continuing. If Engage does not return a response in time, you’ll need a fallback with a retry function to handle this.

Engage's retry policy

​
2 - Contacts flow

Contacts are the backbone of the data stored in Engage. Each one represents an individual customer. Here is how to work with them.

​
Contact creation

Creating a contact in Engage consists of these steps:
1

Search for the customer

First, check if the contact already exists in Engage, using this endpoint:
In the query string of this request you will send some identifier of the contact, such as their email or mobile phone number.If a contact exists, Engage returns their unique contactId value.If a contact doesn’t exist, you’ll get error code “404 contact not found” and must proceed to the next step, where you will create a contact for this customer.

Read more about identifying contacts here

2

Create the customer in Engage

Now you know the customer does not already exist as a contact in Engage, you can create them using:
Engage returns HTTP Code 201 if the creation has been successful.In the response payload you’ll get a JSON with the contact’s full information.
3

Store the customer contact ID

In both of the steps above, the GUID of the created contact will be returned as the id value in the response payload. Store this value for that contact in your own system and use it in the future for looking them up. This simplifies your flows and reduces unnecessary delays and API calls to Engage.

​
Contact creation error handling

When no response is received from the Engage API, or when the response has errors, you’ll need a plan in place to ensure that no data is lost.
  • Validation errors: Here, something in the data you sent was wrong. You should follow the error instructions to ensure good data quality before you retry.
  • No-response error: In the case of no answer, or when you get a 500 or 504 error, you should perform a retry.

Contact data validation

API retry policy

If errors remain, or no response is received, you should save contact changes to local XML files in your system while the disruption is underway. Then, when the connection has been restored, these files can be transferred to Engage to update the contact data, in one of these two ways:
Here you copy the XML file you created to your FTP folder, where it is then uploaded to Engage and all affected contacts are updated.
When uploading XML files via the FTP, new contacts might be created, but their contact GUIDs will not be returned from Engage. Therefore, the next time that contact is identified, you’ll need to manually check if their GUID already exists in your systems, and save it there if it doesn’t.
You can send your saved contact changes to Engage using the bulk API:
Posting data like this puts it in a queue that Engage handles asynchronously. In the meantime, you can continue with your normal workflow.

The bulk API

​
Updating contacts

When a customer changes some personal data (new address, new name, change in some consent) you’ll need to do an update to sync those changes to Engage. If the Engage contactId has been saved in your system, as recommended above, you will not need to query Engage for it first and can just continue directly to the updating. However, if the contactId, for whatever reason, has not been saved, then a lookup to the Engage API must be done to fetch it, using the general lookup endpoint along with some identifying information:
When you have the contactId, the update is then done like this:
The contact attributes to be updated are sent in the request payload.
You can’t use this endpoint to update a contact’s contact type. This has to be done using the /contacts/{contactId}/updateContactType endpoint. See the “Upgrading a contact” section below.
When updating contacts in Engage, be sure to send only the changes. Empty or null values sent in an update payload will overwrite any existing values which is probably not what you want. Engage will return a 200 or 202 response code to show the request was successful.

​
Contact update error handling

Like in the contact creation case, it’s important to have a fallback in place for when problems occur, such as when Engage is down, or does not respond, or return error code 500 is received. Again, if your first call is unsuccessful, perform a retry.

Engage's retry policy

If that fails, implement your local file fallback, saving changes that will be sent in later when the connection has been restored, using either the Engage FTP, or the bulk update endpoint.

​
Fetching contact information

The need will arise to fetch a contact’s data, for example when presenting their personal information, their purchases or their active promotions on My Pages in your e-com. There are three endpoints used here:
Fetch a contact's personal data
Fetch a contact's transaction history
Fetch a contact's active promotions
Important to remember:
  • Cache the response you get here and use that data if the page was to be reloaded. This is to avoid repeated API calls, which can lead to loading delays and a worse user experience.
  • You should only fetch what you need. If you just want to view purchase history, then just use /contacts/transactions. For personal data, use only the first endpoint of the three above.
  • All three endpoints use contactId to identify the contact. Now we’ll consider each one separately.
To fetch the full contact data use the first endpoint:
This returns a JSON with the contact’s personal information (but not transactions or promotions). This is useful, for example, to get a contact’s postal address, see the store where they signed up, or to display their personal information on their My Pages in your e-com.Which information you will display and how is up to you. Engage will return all contact information and you must then filter out what you wish to show for your customer.
To fetch the contact’s purchase and returns history, along with article data, use the second endpoint:
The contactId is sent as a query string parameter.This endpoint allows you some control in paginating the response.
Purchases and returns are both present in the data received from this endpoint.
To fetch all of the contact’s active promotions use the third endpoint:
You have the option to restrict the response by promotion type (ECOM, POS).A promotion will be returned if both the assigned promotion AND the main promotion (the “template” it was created from) are active. Redeemed promotions may be included in this response if they otherwise fulfill the criteria for being active.

​
Upgrading a contact

Engage can handle multiple contact types. For example, you might want to separate your newsletter subscribers from account holders, so you will have a contact type for each. An account holder usually has contact type “Member”. Ideally,this is where you want all your contacts to be. Changing a contact from other type to “Member” is called upgrading. Upgrading contacts is done using the following endpoint:
When upgrading a contact to a member, it’s common to enrich their information using the regular update method shown above.

​
3 - Transactions flow

A transaction can be seen as the “receipt” showing what the contact has bought. A transaction can contain many items, those that were purchased as well as those being returned. Transaction are sent to Engage and saved there, using contactId to connect them to a specific contact. The endpoint used to save them is:
Save transactions to Engage
The /orders endpoint also exists which is used to trigger automations and transactional communication. Don’t confuse these two.

​
Saving a transaction

  1. First check if the customer already exists as a contact in Engage.
  2. If they don’t exist, you’ll need to create them (and remember to save their contactId in your system for future use).
  3. Now POST the purchase information to the /receipts endpoint shown above, with the payload data in the correct JSON format.

Sending purchase information

​
Saving a transaction error handling

You’ll need a plan in place to handle when no response is received from the Engage API, or if the response has error code 500. This is to ensure that no data is lost until the connection is restored. As always, there are two approaches here:
  1. Retry: If your first call is unsuccessful, perform a retry.
  2. Local XML: If errors remain, or no response is received, you should be ready to save the transactions to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Engage via the FTP server.
If you’ve tried to create a contact during your transaction flow, or have updated contact information, then you’ll have to handle that too when the connection is down. Remember also that when uploading XML files via the FTP, contact GUIDs will not be returned from Engage for any new contacts created. Therefore, the next time that contact is identified, you’ll need to check if their GUID already exists in your systems, and save it there if it doesn’t, to reduce unnecessary API calls and improve your flow.

​
4 - Promotions flow

Promotions can be created and assigned to contacts in Engage, and then fetched for display in your e-com or POS. You will need to redeem (mark as used) any promotion that is applied to a purchase. Some things need to be done before a promotion can be used:
  1. Set up the promotion in your own ECOM/POS/ERP using whatever discount rules might apply.
  2. Set up a matching promotion in Engage.
  3. In Engage, assign the promotion to one or several contacts.

Set up a promotion in Engage

An active promotion can either be exported by XML from Engage to the integrating system, or it can be fetched over the Engage API in real-time. This section will focus on fetching promotions in real-time via the API.

​
Promotions endpoints

The relevant endpoints are:
Assign a promotion

​
Displaying promotions

When working with promotions you’ll need to decide if they are to be shown in the POS or in the customer’s My Pages or both, and build the functionality for doing that yourself. These steps will just go through how promotions are fetched and redeemed, not how they are displayed.

​
Redeeming promotions

Redeeming a promotion in Engage is vital to prevent is from being used again, and to also connect it to the purchase where it was used, for purposes of segmenting and reporting.
1

Fetch promotions

Fetch a customer’s active promotions with this endpoint, using contactId in the query string:
You can select promotions based on redemption channel (for example, some might only be available offline / online) by adding the “redemptionChannelType” attribute as “POS” or “ECOM” to the query string.
2

Get the response

In the API response, Engage returns the available promotions for that customer.
3

Apply the promotion

You can now use your price logic to display and apply the promotion as a deduction at checkout.
4

Update customer information

If a customer has updated their information during the purchase, Engage needs that updated information. Use the usual endpoint for updating contact data:
5

Redeem the promotion

Now redeem the promotion with the /redeem endpoint to stop it from being used again:
This will set the promotion to “used” in Engage for that contact.
6

Include promotion with transaction

The promotion identifier should also be included in the API call that is used to register the transaction, along with the rest of the transaction’s data, to allow Engage to match the receipt to the promotion.

Registering a purchase

​
Redeem promotions error handling

You’ll need a plan in place to handle when no response is received from the Engage API, or if the response has error code 500. This is to ensure that no data is lost until the connection is restored. As always, there are two approaches here:
  1. Retry: If your first call is unsuccessful, perform a retry.
  2. Local XML: If errors remain, or no response is received, you should be ready to save the redeemed promotion to local XML files in your system. Then, when the connection has been restored, these files can be transferred to Engage via the FTP server.
If you’ve tried to create a contact during your promotions flow, or have updated contact information, then you’ll have to handle that too when the connection is down.Remember too that when uploading XML files via the FTP, contact GUIDs will not be returned from Engage for any new contacts created. Therefore, the next time that contact is identified, you’ll need to check if their GUID already exists in your systems, and save it there if it doesn’t, to reduce unnecessary API calls and improve your flow.

​
5 - Orders flow

An order represents the goods and services being purchased (or returned) at a given point in time, whether online or in-store. Unlike a transaction, an order’s data can change and may be updated multiple times throughout its life-cycle, for example when its status changes, or when line items are added, updated, or removed. Orders are sent to Engage using the contact’s contactId, in the same way as transactions. The endpoint used to save them is:

​
Creating an order

Creating an order in Engage consists of these steps:
1

Search for the customer

Before an order is sent, always check that the contact already exists in Engage, using this endpoint:
Send an identifier such as email or mobile phone number in the query string. If the contact exists, Engage returns their contactId.If not, you’ll get error code 404 contact not found and must create the contact before continuing.
2

Create the customer, if needed

If the contact doesn’t already exist, create them first:
Store the returned contactId in your own system, just as you would for a transaction, so it can be reused for future orders without an extra lookup.
3

Send the order

Once the contact is confirmed to exist, POST the order data to the orders endpoint:
The request is validated on receipt. If the format is valid, Engage responds with 202 Request has been accepted together with a jobId, which can be used to poll the /jobstatus endpoint and confirm when the order has finished processing.
Processing is asynchronous, so a successful 202 response does not yet mean the order is stored. If you need to trigger an action based on the order, either poll /jobstatus for a Completed status, or use an embedded order action as described below.

​
Order error handling

As with contacts and transactions, you’ll need a plan for when no response is received from the Engage API, or when the response contains errors.
  • Validation errors — something in the sent data was incorrect. Follow the error instructions and correct the data before retrying.
  • No-response error — in case of no answer, or a 500/504 error, perform a retry.
  • Contact missing — if the order data is valid but the referenced contact doesn’t exist, Engage returns status CompletedWithErrors. In this case, delete the order, create the contact ,and then register the order again.
If errors remain, or no response is received, save the order data to local files in your system while the disruption is underway, and resend it once the connection is restored, in the same way as the fallback used for contacts and transactions.

​
Triggering automations for an order

Once an order has been processed by Engage, it can be used to trigger an automation, for example an order confirmation or shipping notification. There are two ways to do this. Option 1 — Call the action endpoint with a VersionTag Trigger the automation by calling the action endpoint:
To make sure Engage uses the correct data when communicating, this call must include a VersionTag. The VersionTag is returned once a change to the order has been processed, and can be fetched either from the /jobstatus endpoint after creating or updating the order, or from the /orders endpoint directly.
This approach requires you to first poll for the order’s Completed status (or fetch the current VersionTag from /orders) before calling the action endpoint.
Option 2 — Include an embedded order action As a simpler alternative, include an embedded order action directly in the payload when creating or updating the order:
Add your instructions as an action object in the request payload. As soon as the order reaches status Completed, Engage automatically triggers the automation — no polling or separate call needed.
An embedded action is only executed if the order is successfully processed and reaches status Completed. If processing fails — for example due to a validation error — the embedded action is discarded and the automation must be triggered manually afterwards.
In short: use embedded order actions whenever possible, since they remove the need for polling. Fall back to the action endpoint with a VersionTag when you need to trigger an automation independently of an order being created or updated — for example, later in the order’s life-cycle.

​
Summary

The most important design considerations when connecting your client system to Engage from scratch are these:
  1. The connection is usually synchronous, meaning you’ll need to wait for a response from Engage before proceeding in your flow. The average response time for the API endpoints is generally short, but longer response times can happen.
  2. Always have a retry policy in place, in case of network problems or the API slowing due to heavy traffic. Retry logic makes your solution more reliable.
  3. Build any redundancy and backup solutions on the client side. For example, a purchase should always be possible to complete even if you can’t get an answer from the Engage API in a reasonable time for your scenario.
  4. Implement error handling for extraordinary situations when the connection to Engage is down. Do not make your vital business processes depend on Engage always being reachable.
  5. Whenever possible asynchronous flows should be used for non-time-critical API calls, for example sending orders and transactions to Engage for storage of purchases and triggering automations.
  6. Ensure that your client application can handle heavy load and high data volumes without exceeding the API rate limits, for example, by implementing queues for non-time-critical messages.
  7. Any contact IDs returned from Engage should be saved in your local systems and used in following requests to avoid unnecessary traffic to Engage, to simplify and speed up look-ups, and to generally improve your customer’s experience.

API retry policy

API rate limits