Integrating your e-com

This guide walks you through integrating your e-commerce platform with Voyado Engage to unlock powerful loyalty, communication, and personalization capabilities.

​

1. The prerequisites

To start building an integration with Voyado Engage, here’s what you need:

• An Engage tenant: This is the instance/environment connected to your Engage acount
• API key: You must generate this in Engage and use it in all API interactions
• Base URL: You must know your base URL of the form https://[tenant].voyado.com
• Contact types: At least one contact type (such as “Member”) should be configured
• Stores: At least one store, retpresented by storeExternalId should be defined for test data

Additional data (custom attributes, more stores, etc.) can be added later as needed.

​

2. The Engage API

Syncing customer data, transactions and other data between your systems and Engage is done via the Engage API. You will need to know how to work with the API and what security considerations and best practices exist.

​

2.1 Required parameters

All integrations with Engage require a secure API connection. For that, the following parameters must always be configured and stored safely in your integration layer:

• Base URL - Your Engage environment endpoint
• API Key - Your authentication key generated in Engage
• Source - A string identifying the system or integration sending the data (such as “ECOM”)
• StoreExternalId - A unique identifier per store, site, or market

These parameters are used in all API calls when creating contacts, submitting orders, sending receipts, or triggering transactional emails.

​

2.2 Integration approaches

Integration can be done through:

• Using a custom build which you code for your specific client setup
• Developing a reusable connector (if you are using multiple clients)

​

3. Working with customer data

When handling customers in your e-com, you always start by checking if they exist as a contact in Engage. If they don’t exist you’ll need to create them there before proceeding.

​

3.1 Identifing a customer

The default unique identifier for contacts in Engage is email but other options exist such as:

• Mobile phone number
• Member number
• Personal identiy number

See here how to find a specific contact in Engage:

​

3.2 Registering a customer

If no match is found, you will need to create a new Engage contact for the cusomter using available data (name, email, address, etc.). Include the following in your creation payload:

• Source: For example “ECOM”
• StoreExternalId: Reflects the customer’s market/shipping country
• Country: Set from address, site geo-location, or store settings
• Language: Based on site language or customer choice (ISO 639-1)

​

3.3 Displaying customer info

The /contactoverview endpoint is used fetch the customer’s full data profile in Engage (known as the enriched profile). Useful data points from the enriched profile are:

• First name
• Last name
• Address
• Gender
• Birthday
• Communication preferences
• Loyalty level
• Points
• Available vouchers
• Available promotions
• Consents

Use this data, for example, to display loyalty data on “My Pages” and in checkout.

​

3.4 Updating customer info

When a customer updates their data (for example name or address), you’ll need to push that update to Engage.

​

4. Working with receipts

Engage uses receipts (the total data of a customer’s transaction) to enable personalized experiences and analytics.

​

4.1 Sending receipts

You should sync the receipt to Engage when the order is completed (delivered). This ensures that point calculations are based only on what the customer has actually received.

​

4.2 Receipt details

Here are some important details to consider about receipts:

​

4.3 Handing returns

When a return is made, you must send a return receipt containing the details of the returned products.

​

5. Working with orders

Engage supports the tracking of the entire order journey, and can also send communications related to order updates and changes. Order updates can be sent for:

• Pending orders
• Cancellations
• Shipments
• Deliveries
• Returns

​

5.1 Order communication

When the state of orders change, marketing automation flows in Engage can be triggered.

​

6. Promotions and vouchers

Use Engage’s segmentation and automation tools to assign individual promotions or vouchers, such as “10% off for Gold members” or “€10 Voucher“. Some important points about promotions and vouchers:

• Promotions are created in Engage and referenced in the e-com by an external ID
• It is the e-com that handles pricing rules and redemption logic
• It is Engage that handles personal assignments of the discount

​

7. Web activity tracking

User behaviour on-site can be traked with either:

• Tracking script (client-side)
• REST API (server-side)

You can track:

• Product page views
• Cart events

​

8. Soft Identification

Soft identification connects a contact to a session (for example, by an email link) without requiring any login. Engage decrypts an encrypted JSON in the URL query string to perform the identification, Each client has a unique shared key for decoding the identification token.

​

9. Data migration before go-live

Before go-live, we recommend importing your historical data into Engage to ensure continuity in customer insights and personalization. Common data that should be migrated incudes:

• Contacts (members, newsletter signups)
• Transactions (purchases, returns, receipts)

​

9.1 Migrating contacts

This can be done in several ways:

• Contacts API: Used for real-time or low-volume imports of contact data
• Batch contacts API: Best option for importing large volumes of contact data
• CSV upload: Suitable for smaller one-time imports via the Engage UI
• XML upload via FTP: For scheduled or high-volume contact imports

​

9.1 Migrating transactions

This can be done by:

• Transactional API: For full control and real-time logging of purchases and returns
• XML via FTP: Recommended for batch imports of large transaction volumes

Always follow Voyado’s API rate limits to avoid throttling during migration: