Startup guide

This guide covers the step-by-step actions you’ll take when integrating Voyado Engage to your system, as well as the basic concepts. 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 intergrating 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 - Initital 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:

   GET api/v3/contacts/id
   

   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:

   POST api/v3/contacts
   

   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 rety 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 two ways:

Method 1 - FTP

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 manally check if their GUID already exists in your systems, and save it there if it doesn’t.

Method 2 - Bulk API

You can send your saved contact changes to Engage using the bulk API:

POST /api/v3/contacts/bulk

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:

GET api/v3/contacts/id

When you have the contactId, the update is then done like this:

PATCH api/v3/contacts/{contactId}

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

GET /api/v3/contacts/{contactId}

Fetch a contact's transaction history

GET /api/v3/transactions

Fetch a contact's active promotions

GET /api/v3/promotion-assignments

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.

Fetch a contact’s personal data

To fetch the full contact data use the first endpoint:

GET /api/v3/contacts/{contactId}

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.

Fetch a contact’s purchase history

To fetch the contact’s purchase and returns history, along with article data, use the second endpoint:

GET /api/v3/transactions

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.

Fetch a contact’s active promotions

To fetch all of the contact’s active promotions use the third endpoint:

GET /api/v3/promotion-assignments

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:

POST /api/v3/contacts/{contactId}/updateContactType?contactTypeId=Member

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

POST /api/v3/receipts

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 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.

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

GET /api/v3/promotion-assignments

PATCH /api/v3/contacts/{contactId}

POST /api/v3/promotions/codes/{promotionId}/redeem

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:

   GET /api/v3/promotion-assignments
   

   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:

   PATCH /api/v3/contacts/{contactId}
   
5. Redeem the promotion

   Now redeem the promotion with the /redeem endpoint to stop it from being used again:

   POST /api/v3/promotions/codes/{promotionId}/redeem
   

   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.

   POST /api/v3/receipts
   

   

   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.

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 rety policy

API rate limits