Setup and configuration

The first step is to input the base URL and API key for your Engage account.

The base URL uses your Engage tenant name, which is the unique name connected to your Engage account. For example, if your tenant name is "example" then your base URL would be:

https://example.voyado.com

If you are connecting an Engage staging environment, you would use:

https://example.staging.voyado.com

Whatever your URL is, it goes into the first field.

The API key is used for secure communication between Engage and the app. You can generate API keys yourself in the Configure Engage section of your Engage environment. Go here to see how that's done.

API keys will look something like this:

1111fff1-4dc6-4a00-a5ce-e060c42f2222

Once the key entered in the second field, select "Connect". The app will test the connection to Engage.

If that connection is successful, the panel will then look like this:

You can now continue to the next step.

The task monitoring service tracks your app’s health, showing you if the syncing of data between Shopify and Voyado Engage is running successfully or not. You can access the task monitoring service under Task overview on the left-hand menu in your Shopify store, in the settings for your Voyado Engage app.

In this section of the configuration, you'll specify how the task monitoring service will run.

Order silence period: If this amount of time passes and no orders are successfully synced between the app and Engage, the system will raise an alert. This can be used as an indication that something has gone wrong.

Scheduled order silence check window: Here you can specify the daily time window during which order silences will trigger an alert. Useful if, for example, you know that you never get any orders during the night.

Error rate threshold: The percentage of errors out of the total that will trigger an alert.

Alert notification addresses: Here you input the additional email addresses that you want to receive any alerts. Note that the email address connected to your Shopify store will always receive these alerts.

Once everything is entered to your liking, press "Save".

You can find a more detailed description of the task monitoring service here.

Each one of your customers in Shopify have a country to which they “belong“, which depends on the store front or market they signed up with or placed their first order from.

In this step, you'll tell the Engage app for Shopify which country each of your e-com stores maps to (ships from).

Select "Add mapping" to start connecting your Engage stores to a country (in this image, some mapping has already been done).

Now select the first option, "Shipping country". You won't be using the "Shopify POS location" option here.

You will see two drop-downs. The first has your Voyado Engage stores, the second the shipping countries.

Select the country / locale for each of your Engage stores. A Rest of the world fallback value must be set for countries not specifically mapped and for customers without a location in Shopify that can be synchronized.

Add all the stores you want to use and select "Save". The panel will then look something like this:

Here you choose which personal identifier to use when looking up customers in Engage.

The app deals with two customer types: Member (account holders) and Contact (guest customers). The type Member is always used, and here you'll decide if you want to also use type Contact or not.

Both Contact and Member: This allows both contact types Contact and Member to be used.

Create everyone as Member: This means that all customers will be of contact type Member (recommended).

Here you select the point at which an order will be stored as a receipt in Engage. This will either be at the order confirmation stage or when the order has actually been fulfilled.

Enabling this setting will allow transactional communication to be sent from Engage.

These transactional emails can be either:

If you want to use back-in-stock notifications in Engage, you'll need to enable this option.

A back-in-stock theme element is available in the theme editor. This can be added to your product template, allowing customers to subscribe for back-in-stock notifications in the e-com. With inventory sync enabled, you'll then be able to act on these subscriptions in Engage when something comes back in stock.

See here for detailed instructions on how to work with the app's back-in-stock functionality.

The group currency is set up in your Engage environment. You'll need to write in the same value here. Doing this will convert and store the monetary values in all orders using the correct conversion rate.

Group currency names follow the ISO 4217 standard.

Shopify has a Voyado Engage app block which you can embed into your Shopify theme. By selecting “Customize theme” in the panel, you will be taken to the editor for your current theme.

Here, using the side menu, you can embed the Voyado Engage app block in all pages (apart from the checkout page).

Under Template, select "Add Section".

Go to the "Apps" tab and select Voyado as seen in the image.

Now the Voyado app block appears.

This app blocks can fetch loyalty data from Engage and display it, after the customer has identified themselves on-site either by logging in or by soft identification (see the following section).

Soft identification (also called Soft ID) allows a customer to be identified in a Shopify store when they arrive there via a personalised link, for example from an Engage email send-out. To activate this tracking, select "View app embed" in this panel.

This will take you to a new page in Shopify, where you'll see this:

Enable the “Soft ID Detect App Embed” toggle. Be sure to select "Save" in the top right of the page.

You'll need to also insert the decrypt key, which happens in the next step below.

Once these two things are done, your app block with be filled out with loyalty data upon customer identification.

For tracking to work, you'll need to input and save the encryption key. Copy the "Encryption key" from the Configure Engage > Soft identification section of your Engage environment.

Then go to the "Soft identification decrypt key" area of the Shopify app configuration and enter the soft identification decrypt key for your production environment. Don't forget to press "Save".

In this section you can add fallback content to the app block if the customer has been identified through an email link but hasn’t signed in yet. This will allow you to prompt the customer to sign in, allowing them to use their personal discounts and redeem them in Engage.

Web pixel tracking allows the app to track user behavior, enabling many useful functions.

"Enable cart tracking" allows you to track cart activity on-site and trigger abandoned cart email through Engage.

"Enable identification of customers by email at checkout" enables a look-up of customers in Engage when they give their email address at the POS. By also selecting "Create a customer in Engage if their email is not found" you allow that customer to be created in Engage if the email they gave is not found there.

"Enable product view tracking" lets you track what your customers are viewing and send it to Engage. Abandoned browse is also supported.

The choice of "Production" or "Staging" here depends on your Engage environment. If the word "staging" appears in your base URL (see Account Connection above) then choose Staging here. Otherwise, choose Production.

Select "Save" and this step is completed.

Read more about the "Enable identification of customers by email at checkout" feature on this page.

If you plan to use promotions or vouchers across Engage and Shopify, you'll need to activate that here. Both promotions and vouchers from Engage are handled as different kinds of discounts in Shopify.

"Enable promotion sync" allows you to use promotions between Engage and Shopify. Promotions need to be first created as a discount in Shopify, then as a multichannel promotion in Engage, using the same unique ID as the Shopify discount to link them. The promotion is then displayed in the loyalty app block in Shopify and redeemed back to Engage when used.

"Enable loyalty voucher sync" allows vouchers to be created in Engage, synced across to Shopify, displayed and used there, and then redeemed back to Engage when they are used.

For a more detailed look at how promotions and vouchers are set up and used, read this section.

This allows you to migrate customers and orders from your Shopify account to Engage through the Voyado Engage app, enabling you to start your Engage journey with your data already in place.

If you have the Shopify POS integration with Engage, this step will migrate that data as well.

There are two cases to consider here:

Case 1 - Migrating customers from Shopify to Engage

Here, you'll select the "Import customer data" options and then hit "Submit". This will migrate all your Shopify customers (and POS customers, if applicable) to Engage. If they don't already exist in Engage, they will be created there as contacts.

If a migrated customer already exists in Engage, the app will not update their data, but just fetch the contactId reference from Engage and store that in Shopify.

This app can also handle customers that were created only in Engage or imported there through other channel, such as a CSV file import, or via some other platform. This is important in the next step when migrating orders.

Important

"Import customer data" will fetch and store the contact ID of any customer who was created in Engage outside of the app.

Case 2 - Migrating orders from Shopify to Engage

This starts a migration of Shopify orders, both purchases and returns, to Engage (and POS orders, if applicable). For this to work, the customer who made the order must already exist as a contact in Engage. That's why you'll always select the "import customer data" option here. Doing this ensures that customer data is synced before orders data is migrated (as there always needs to be a customer to connect an order to).

If, for example, a customer exists in Engage but not in Shopify, the app, when matching orders to customers, will fetch the contactId reference from Engage and store it in Shopify. This is relevant for any customer data imported into Engage outside of the app.

The order data option allows you to specify "Start date" and "End date". Then you will only sync those orders created inside that time window. Hit "Submit" to start the migration.

Note

When doing an order data migration, the app will process the data in this order: customer import first, and then the order import.

Here you input the API key (or keys) to be used when running Shopify headless.

See here for detailed information on running headless Shopify with Engage.

You can sync all preference updates made to contacts in Engage directly to Shopify using a webhook system. If you're doing this, this is where you add the encryption key and webhook URL to use. In this article you can read a full description of how webhooks are used with the Voyado Engage app.

Enabling this does not change any settings in Shopify. But if you have the "Email" option set to to “Preselected” in Settings > Checkout > Marketing options you'll need to enable this too.