> ## Documentation Index
> Fetch the complete documentation index at: https://partner-integrations.voyado.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuration guide
Here are the steps in configuring the Shopify app for Voyado Engage.
## 1 - Install the app
In Shopify Admin, go to **Apps** → **Shopify App Store**.
1. Search for **Voyado Engage**.
2. Click **Add app** and complete the installation.
You will need an Engage account to proceed. Choose the option that applies to you:
1. In the app's first screen, choose **I already have an account**.
2. Voyado might need to enable Shopify support for you. Contact your Voyado team.
3. When that is done, proceed to step 2.
1. In the app onboarding, fill in **Company name** and **Company number** (or equivalent).
2. Hit **Submit**. Voyado will now contact you to create the account.
3. Once your Engage account is ready, re-open the app and select **I already have an account**.
4. Now proceed to step 2.
You can always get back to the app configuration later via **Apps** → **Voyado Engage** → **Settings** in Shopify.
## 2 - Connect Shopify to Engage
In Shopify, open **Apps** → **Voyado Engage** → **Settings**.
### Voyado API Domain
Under **Engage account connection**, fill in **Voyado API Domain:**
* Production: `https://[tenant].voyado.com`
* Staging: `https://[tenant].staging.voyado.com`
Replacing `[tenant]` with your Engage tenant name.
### Voyado API Key
Generate this in **Config Hub** inside your Engage environment (API key for the Shopify app).
1. Click **Connect**.
2. Verify that a confirmation panel appears showing the connected Engage URL.
### Changing environment
If you need to change which Engage environment your Shopify app is connected to, you can:
1. Go to **Settings** and then **Disconnect**
2. Enter a new API Domain and API Key
3. Press **Connect** again
All app configuration (mappings, toggles, and so on) will be retained when you disconnect/reconnect
## 3 - Map countries to stores
Now you will map your countries in Shopify to stores in Engage. The store -> country mapping determines which Engage store that each Shopify customer and order belongs to. This is critical for segmentation and reporting.
To do this:
1. In Shopify, open **Voyado Engage** → **Settings** → **Voyado Store to Country Mapping**.
2. Click **Add mapping**.
3. For **Mapping type**, choose **Shipping country**.
4. For **Voyado Store**, pick the Engage store (type `ECOMM`) which will handle that shipping country.
5. For **Shipping country**, select the corresponding country from Shopify.
6. Repeat these steps for each market you sell to.
7. Set a **Rest of the world fallback store** (mandatory) for customers with unmapped or missing country.
If you have Shopify Markets (one store, many countries), you'll typically have one `ECOMM` store per country in Engage, and will map each shipping country to the right store.
## 4 - Contact synchronization
Now you will determine how customers from Shopify are created as contacts in Engage.
Open **Voyado Engage** → **Settings** → **Contact synchronization** in the app.
### Identification method
Pick **Customer identification method**:
* **Identify by email only (recommended)** - lookups only by email (this is unique in Engage).
* **Email first, then phone number** - only if you're okay with the risk of non-unique phone numbers.
* **Phone number first, then email** - the least recommended option.
Use **Identify by email only** to avoid duplicates.
### Contact type
Choose **Customer contact type**:
* **Create everyone as Member (recommended)** - Ths means all Shopify customers will be stored as Members in Engage.
* **Both Contact and Member** - Not recommended with Shopify's **New Customer Accounts**, because all new customers will effectively end up as Contacts.
With Shopify's **new customer accounts**, Voyado recommends **Create everyone as Member** so all e-com shoppers are treated as account holders in Engage.
## 5 - Orders to receipts
This determines when orders in Shopify will be sent to Engage to become transactions / receipts. Do this:
1. In the Voyado Engage app, go to **Settings** → **Receipt sync stage** (wording may vary slightly).
2. Choose when an order should be stored as a Receipt in Engage, either:
* **When Order is Unfulfilled**
* **When Order is Fulfilled**.
Once a receipt is created, it can be used for segmentation and point calculations and shown on dashboards in Engage.
Make sure **Store to Country Mapping** is in place first, otherwise receipts will fail to sync.
## 6 - Order notifications
This determines how transactional emails are sent from Engage.
1. In Engage, prepare your automation workflows and email templates for:
* Order confirmation
* Order shipped / partially shipped
* Order cancelled
* Order refunded
2. In Shopify, for Shopify Plus stores, disable Shopify's native transactional emails (where allowed) so customers don't get duplicates.
3. In the Voyado app **Settings**, enable **Order notifications** (name might vary slightly) so Shopify events trigger Engage automations with mapped order data.
## 7 - Back in stock sync
This keeps the inventory levels synced from Shopify to Engage, allowing back-in-stock functionality to work.
### Prerequisites
Before you start configuring this in Shopify, make sure the following are in place in Engage:
* **Product feed connected and active** - Your Shopify product feed must be imported into Engage and updating regularly.
* **Back in stock module enabled** - The Back-in-Stock feature must be activated in the Engage tenant.
* **Back in stock email/SMS template ready** - There is at least one template (usually email) that can be used for the notification.
* **All relevant products exist in the feed** - If a product isn't in the feed, Voyado can't send Back-in-Stock notifications for it.
If any of these are missing, it's vital that you fix them first (this is usually done together with your Voyado CSM or implementation team).
### Inventory Sync
Do this in the Shopify app:
1. In Shopify Admin, go to **Apps** → **Voyado Engage**.
2. Open the app and go to **Settings**.
3. Find the toggle for **Inventory Sync** and turn it "ON".
4. Make sure the locations that handle online orders are included in the stock levels that are synced (meaning, the same locations Shopify uses for your online store).
This step ensures that when stock levels change in Shopify, Engage is updated and knows when to trigger notifications.
## 8 - Soft ID Detect App Embed
To enable this in Shopify:
1. In Shopify Admin, go to **Apps** → **Voyado Engage**.
2. Click **View app embed**
3. In the App Embed view, enable the toggle:
* **Soft ID Detect App Embed**
4. Click **Save** in the top right corner.
This toggle must be enabled for Soft ID (and tracking features) to work at all.
## 9 - Soft ID decrypt key
Here you'll configure the soft identification decrypt key. This key is required for Shopify to decrypt the identifier coming from Engage-generated email links.
1. Login to **Voyado Engage**.
2. Go to **Administration** -> **Configure Engage**
3. Open **Soft identification** section
4. Copy the **Encryption key** (for the correct environment, usually production)
5. Go back to **Shopify admin** -> **Apps** -> **Voyado Engage**
6. Paste the key into **Soft identification decrypt key**
## 10 - Web pixel tracking
Web pixel tracking is used in abandoned cart, abandoned browse and products of interest. Before you start configuring this in Shopify, make sure the following are in place in Engage:
* Your **Product feed** must be imported into Engage and updated regularly
* The **Soft ID Detect App Embed** must be active (see step 8 above for details)
Now follow these steps:
1. In Shopify, open **Voyado Engage** → **Settings** → **Web Pixel Tracking**.
2. Enable **Enable cart tracking** for abandoned cart flows.
3. Enable **Enable identification of customers by email at checkout** (and also **Create a customer in Engage if their email is not found** if you want auto-creation to function).
4. Enable **Enable product view tracking** for products of interest / abandoned browse.
5. Confirm that the environment configured (production or staging) matches your Engage API domain.
## 11 - Loyalty & promotions
Now you will decide how loyalty and promotions are shown in the storefront by configuring theme blocks and checkout appearance.
### App theme block
1. In Shopify Admin, open **Voyado Engage** and select **Customize theme** in the app.
2. In the Theme Editor, click **Add section** → **Apps** → **Voyado**
3. Insert the **Loyalty / Promotions** block where you want it (for example, **My account**).
4. Now save the theme.
### Vouchers & promotions
In Shopify:
1. Go to **Voyado Engage** → **Settings**
2. Enable **Promotion sync** (for multichannel promotions from Engage)
3. Enable **Loyalty voucher sync** (for reward vouchers from Engage)
4. Enable **Combination options** and choose whether a voucher can be combined with:
* Product discounts
* Order discounts
* Free shipping discounts
In Engage:
1. Set up **Reward vouchers** (from points) as needed.
2. For promotions, make sure the **External promotion code** exactly matches a discount code in Shopify
### Loyalty checkout extension
If you're on Shopify Plus:
1. Go to **Settings** → **Checkout** → **Customize**.
2. Add the **Loyalty Checkout Extension** (usually near the discount code field).
3. Configure whether to require login in order to show offers.
4. Configure label overrides (optional).
5. Configure whether you show promotions, vouchers, or both (depends on which sync toggles are on).
The Checkout UI extension applies for Shopify Plus customers only.
## 12 - Data import
In this step you will be importing existing customers and orders. If you're onboarding an existing Shopify store, run these imports so that Engage starts with the full customer history.
In Shopify, open **Voyado Engage** app → **Data Import**.
### Import customers
1. Choose **Import customer data** and click **Submit**.
2. All Shopify customers (including Shopify POS) are created in Engage if they don't exist.
3. If they do exist, the app just fetches their `contactId` and stores it in Shopify for future linking.
### Import orders
1. In the same screen, choose the date range (**Start date** / **End date**) for orders you want to migrate.
2. Click **Submit** to import orders.
3. Orders are imported only when their customer already exists in Engage (hence customers first).
Be sure to temporarily disable Engage automations that trigger on "New contact registered", "Product purchase", or "New return" so you don't accidentally trigger send-outs during the import of historical data.
