> ## 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.
# Good to know
Here are some good-to-know things about the Shopify - Engage integration.
## 1 - Environment setup
To ensure a stable and implementation, the following is recommended:
Set your **Shopify Development Store** to you Engage staging environment:
```http theme={null}
{tenant}.staging.voyado.com
```
And set your **Shopify Production Store** to you Engage production environment:
```http theme={null}
{tenant}.voyado.com
```
This setup ensures:
* Clear separation between test data and live customer data
* No risk of mixing staging and production contact records
* Clean and controlled store mapping
* Safe testing of imports, automations, promotions, and vouchers
* Reduced risk of data inconsistencies
This is the preferred and most secure configuration.
### Single Shopify production store
In some cases, merchants may only have *a single Shopify production store* and may want to connect it to both their Engage staging (for testing) and then later to their Engage production environment. While technically possible, this setup requires additional care due to how the integration handles environment data.
When the Shopify store connects to Engage:
* The list of Engage stores is retrieved and stored in the app’s internal database
* This store list remains stored even if the app is later disconnected
If the same Shopify store is connected to both Engage staging and Engage production, and the store configurations differ between environments, both sets of stores may remain stored internally.
This can create confusion in store mapping if environments are switched without proper handling.
When running a customer data import:
* Each Shopify customer is linked to a specific `contactId` in the connected Engage environment
* This reference is stored internally
If customer data has been imported into Engage staging, the stored `contactId` values will point to staging contacts.
When later switching to Engage production, those references *must* be updated to point to the production contacts instead.
If they are not updated, order synchronization and automations may reference incorrect records.
If you have previously connected your Shopify store to Engage staging and are now moving to Engage production, these are the steps you *must follow*:
To change your Shopify store connection from Engage staging to Engage production:
1. Disconnect the Voyado Engage app.
2. Enter your Engage production credentials.
3. Click **Connect**.
4. Navigate to **Data Import**.
5. Run **Import customer data** again.
This ensures:
* All customers are re-synchronized
* The correct Engage production `contactId` references are stored
* Future order synchronization and automations use the correct production data
These things must be kept in mind:
* Do *not* skip the contact re-sync step when switching environments
* Avoid running order imports before re-syncing contacts
* If possible, avoid switching environments on a live production store
## 2 - Shopify plan dependencies
There are some dependancies on the Shopify plan you are using.
Displaying reward vouchers and promotions directly inside the Shopify checkout via the Loyalty Checkout Extension requires **Shopify Plus**.
Merchants not using Shopify Plus can still:
* Sync vouchers and promotions
* Allow manual entry of discount codes
However, they cannot embed the loyalty component inside the checkout.
For transactional emails (order confirmation, shipment, cancellation, etc.) to be sent from Engage instead of Shopify:
* Shopify Plus is required to disable most native Shopify emails
* “Order confirmation” must be disabled by Shopify support
Without this setup, there is a risk of duplicate email communication.
## 3 - Customer account theme limitations
There are theme limitations based on the kind of customer account.
The Loyalty app theme block:
* Works only with \*\*Shopify Classic Customer Accounts
* Is not supported for \*\*New Customer Accounts
* Cannot be placed on the checkout page
If a merchant uses New Customer Accounts, the standard loyalty block cannot be used.
The app block requires a theme that supports **Shopify OS 2.0 app blocks**.
Older or heavily customized themes may require adjustments or upgrades.
## 4 - Reward vouchers and promotions
Reward vouchers and promotions are separate features and operate differently.
Reward vouchers are synced to Shopify as discount codes. They are synced only when:
* The customer visits a page containing the Promotions & Loyalty App Block
* Or the Checkout Extension is loaded
Reward vouchers amounts are in the configured **group currency** (which should match Shopify store currency).
If a voucher has already been synced to Shopify, there is a theoretical risk that it can still be used even if redeemed in another channel before the next sync.
This is true for promotions:
* They must first be created in Shopify
* They must then be created in Engage with a matching External Promotion Code
* Promotions are language-specific in Engage and must be configured per language
* Shopify cannot handle duplicate identical external codes
* Only promotions linked to Engage are shown in the loyalty block
## 5 - Synchronization Model
Voucher and promotion synchronization is **trigger-based**, and does not run continuously.
Synchronization occurs only when:
* A page with the loyalty app block is loaded
* Or the checkout extension loads
This is important when setting expectations concerning “real-time” visibility of offers.
## 6 - Data migration constraints
These constraints exist when working with data migration.
Orders *cannot* be migrated to Engage unless the related customer already exists in Engage. Therefore, customer import must always be performed before order import.
If a customer already exists in Engage, the import process:
* Does not overwrite existing Engage data
* Only retrieves and stores the Engage contact ID in Shopify
Existing automations (e.g., “New contact registered”, “Product purchase”) may trigger during migration. This means that automations should be temporarily disabled during large data imports.
## 7 - Receipt & segmentation timing
Orders are only available for segmentation in Engage after they are stored as **receipts**.
Receipt creation depends on the configured sync stage:
* At order confirmation
* Or at fulfillment
Incorrect or missing Store-to-Country mapping (including fallback store) may affect receipt processing.
## 8 - Web tracking and identification
The web tracking features, such as abandoned cart, abandoned browse, product interest tracking, all require that:
* Web Pixel Tracking is enabled
* Soft ID Detect App Embed is enabled
* Checkout Extensibility is activated in Shopify
If a new contact is created during checkout:
* The contact is initially created with `acceptsEmail` set to "false"
* Marketing preferences are updated only after checkout is completed
## 9 - Back-in-stock constraints
These constraints exist for the back-in-stock functionality:
* Products must exist in the product feed even when out of stock
* The “Continue selling when out of stock” setting must *not* be enabled
* The theme block solution does not work in headless implementations (API implementation is required instead)
## 10 - Customer identification
These considerations exist for customer identification:
* Email-only identification is *strongly recommended*
* Phone number identification may lead to conflicts (phone number does not have to be unique in Engage)
Amd due to Shopify's New Customer Accounts structure:
* If both “Contact” and “Member” types are allowed, all customers may be created as Contacts
* To ensure loyalty functionality, “Create everyone as Member” is recommended
## 11 - Browser identifiers and consent
The Voyado Shopify app sets browser identifiers (cookies) to support visitor recognition, customer identification, and cart tracking. This article describes which identifiers are used, when they're created, and what merchants are responsible for when deploying the integration.
## Browser identifiers
The app uses three identifiers:
| Identifier | Purpose | Created when |
| :--------------------------- | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------- |
| `_va` | Stores the Voyado visitor identifier for website tracking and visitor recognition. | The visitor has granted the required consent. |
| `voyado_soft_ident_key_vtid` | Stores a temporary visitor identifier from a Voyado email campaign link to recognize the visitor during that visit. | A visitor arrives via a link in a Voyado email campaign. |
| `voyado_contact_id` | Stores the Voyado contact identifier for an authenticated customer. | A customer signs in and the required consent has been granted. |
### Consent handling
The `_va` and `voyado_contact_id` identifiers are only created after the visitor has granted the required consent. No website tracking events are sent to Engage until that consent has been granted.
The `voyado_soft_ident_key_vtid` identifier is created when a visitor arrives through a Voyado email campaign link, regardless of consent state. This behavior is built into the integration and is not configurable within the Shopify app. Merchants using Voyado email campaigns must ensure this is appropriately described in their privacy documentation.
### Merchant responsibilities
The identifier behavior described in this article is standard and cannot be changed within the Shopify app. Merchants are responsible for determining whether this implementation meets their legal, regulatory, and privacy requirements.
If the standard implementation doesn't meet your organization's requirements, you can:
* Disable the relevant functionality in the app.
* Implement your own website tracking and identification logic outside the app.
When using the built-in functionality, ensure that:
* Your privacy policy describes how browser identifiers and tracking technologies are used on your site.
* Your cookie information reflects the identifiers the app sets.
* Your Consent Management Platform (CMP) is configured to meet your legal and regulatory requirements.
* Your newsletter terms or privacy documentation covers the use of `voyado_soft_ident_key_vtid` for visitors arriving from email campaigns, where applicable.
### Compliance
Voyado provides the technical functionality described here. Voyado does not determine the legal basis for a merchant's processing of personal data or use of browser identifiers.
Each merchant is responsible for their own compliance with applicable legislation, including GDPR, the ePrivacy Directive, and local privacy regulations, and for maintaining appropriate privacy notices, consent mechanisms, and legal documentation.
If you're uncertain whether the standard implementation is suitable for your organization, consult your legal or privacy advisor before going live.
## Summary
The Shopify integration is powerful but has structural limitations. Consider:
* The use of separate Shopify environments whenever possible
* If only one Shopify production store is available, follow the structured disconnect → reconnect → re-sync process carefully when moving from staging to production
* Features can depend on your Shopify plan level (Plus vs non-Plus)
* Checkout extensibility
* Theme and account type compatibility
* Trigger-based synchronization
* Data migration dependencies
* Store mapping configuration
These constraints should be evaluated early in the project to ensure alignment with the merchant's technical setup and business goals.
##