- A Shopify or Shopify Plus store.
- A fully set up and working Emarsys Marketing Platform account, especially the following:
- An Emarsys merchant ID.
- Emarsys API credentials for authentication. For more information on how to create API users, see API users.
- All of the above should already have been set up as part of your standard Emarsys onboarding. If you are missing any of them, please contact Emarsys Support.
- You will only be able to track revenue from email campaigns if you have an enterprise-level Shopify Plus subscription, due to the limitations that come with the standard packages.
- If you have more than one Shopify store, you will need to map each one to a separate Emarsys account.
Installing the Emarsys plug-in
Before you start:
- When you enable customer data synchronization and set up contact field matching, then please consider the following: Our Shopify app will import your Shopify contact data to Emarsys and overwrite any existing values. If you already have contacts in your Emarsys account and you would like to make sure that the details of these contacts will not be lost, before installing the Shopify app, we recommend exporting your initial Emarsys contact database and importing it to Shopify. Please consult Emarsys Support or the Implementation Team before performing an initial contact import so that we can help you to protect any critical data that has been collected in Emarsys, such as opt-in status or contact details.
- If the app is already installed on your store, the installation will be cancelled and you will be redirected back to this page.
- You can exclude certain contacts from synchronization (at contact creation and update in Emarsys) by adding the
emarsys_ignoretag to the specific contact in your Shopify store. Please consider the following:
- Contacts with the
emarsys_ingoretag will not be synchronized during the initial import.
- If a contact already exists in your Emarsys account (e.g. the contact was created manually), then no further updates will take place.
- The contact’s opt-in data will still be synchronized from Emarsys to Shopify (e.g. if a historical contact unsubscribes from a newsletter).
- Emarsys will fetch all standard Shopify Flow events based on webhooks and contacts with the
emarsys_ignoretag may be created with just an email address (without any opt-in data) in order to send transactional messages to them.
emarsys_ignoretag does not affect order synchronisation. Orders made by contacts labeled with this tag will be processed and they will not be identified in Smart Insight.
- Contacts with the
1. Log in to your Shopify store.
2. Install the Emarsys app from the Shopify App Store: https://apps.shopify.com/emarsys-suite
3. Review the requested permissions and click Install app.
4. You will now see the app listed on the Shopify Apps page.
Configuring the Emarsys plug-in
When configuring the Emarsys Shopify plug-in, you can use the plug-in to synchronize various data sets:
- Customer data - Mandatory. You cannot activate other parts of the plug-in without enabling customer data synchronization.
- Events - Optional. Emarsys suggest synchronizing your Shopify events to Emarsys because you can activate specific Tactics with events.
- Product data - Optional. Please note that order data and Web Extend depend on product data.
- Order data - Optional. Please note that you can sync order data only if product data sync is enabled.
- Web Extend - Please note that you can only activate Web Extend if product data sync is enabled.
If you need further assistance, please contact Emarsys Support.
1. Connecting your Shopify store to Emarsys
1. On the Apps page, click the app link to open the app dashboard.
Here you can see a number of boxes, each representing an integration step. The vertical alignment of the boxes indicates the recommended order of the steps you must complete, so you should ideally start with the top box and work your way down.
2. Click Connect in the topmost box, and then enter your Emarsys API username and Emarsys API secret, then click Connect.
- You should already have your API credentials as an API user should have been created as part of your standard Emarsys onboarding. Your technical specialist should know where you store this information.
- If you cannot find your existing API username and secret, or if you do not have any, create a new API user.
Make sure that your API user is authorized to access the
customer.settings API endpoint. Set the toggle for the endpoint in Management > User Management > API Users.
2. Uploading Shopify customer data to Emarsys
- Currently, only the
email addressidentifier is supported by the Emarsys Shopify plug-in for:
- Creating, updating and deleting contacts
- Triggering events
- Synchronising orders
This does not apply to Web behavior tracking, which uses the
- Uploading your Shopify customer data to Emarsys also involves the following actions:
- In the Customers section, click Enable to turn on the regular upload of your Shopify customers to the Emarsys contact database. This will enable you to make use of your Shopify data in your marketing campaigns.
The progress of the initial upload is tracked in the Upload status pane. When it is finished a Live flag will be displayed on the left.
- After the initial upload of your customer data, you will be able to modify the default field mapping. In the Field matching section you can choose which fields to map between Shopify and Emarsys:
- To modify the default field mapping, click Edit field matching.
Note that whenever you modify the mappings, we will upload all your customer data to Emarsys again. Please take into consideration that this action will override any existing contact data in Emarsys, including opt-in data, with the values fetched from your store.
- To check the default field mapping, click Show field matching.
- In the Default matching section, you can match each Shopify customer field with a field in your Emarsys contact database. For more information on limitations related to field matching and data synchronization, see Field matching and data synchronization.
- When you enable customer sync for the first time, the app will pull all your Shopify customers and push them to your Emarsys account.
- By default, the
Shopify IDfield is not supported.
- If you already have contacts in your Emarsys account, make sure that the identification you are using is correct.
- In order to enable transactional scenarios, such as order or shipment confirmation, contact records are created even for guest checkout users in the Emarsys contact database when using the Emarsys Shopify plug-in.
- Please consider the following regarding the
Updated AtShopify standard date fields:
- These fields are mapped and synced automatically to Emarsys:
Shopify Created At
Shopify Updated At
- We do not recommend removing these fields from the Field matching page.
- If you started to synchronize customer data from Shopify to Emarsys before 7 September 2020, then you need to manually trigger the initial sync by editing and saving the Field matching settings, so that this date will be synced for those contacts who were created before 7 September 2020.
- We recommend using the field
Shopify Created Atinstead of the field
date of registration(i.e. the date when contacts were created) especially in the Smart Insight Settings.
- These fields are mapped and synced automatically to Emarsys:
- To synchronize SMS opt-in data between Shopify and Emarsys, proceed to Synchronizing SMS opt-in data.
- To match Shopify metafields to Emarsys custom fields, proceed to Matching Shopify metafields to Emarsys custom fields.
Synchronizing SMS opt-in data
Prerequisite: You need to activate the SMS channel in Emarsys.
To sync SMS opt-in data, you need to map the Shopify
SMS Marketing Consent field to the Emarsys
Mobile SMS Opt-in field.
As a result, SMS opt-in data will be synced from Shopify to Emarsys automatically.
- To enable SMS opt-in data sync in both directions (i.e. from Emarsys to Shopify and the other way around), please raise a support reuqest. Emarsys will manage your request within 2 business days.
- SMS opt-in data is synced in both directions in near real-time.
- Currently, the
SMS Marketing Consentfield is not displayed on customer preview in Shopify. Shopify provides a possibility to collect mobile phone numbers along with SMS consent data. To activate this function, go to the Checkout Settings page in your Shopify store and check the Show an option to subscribe at checkout checkbox under SMS marketing.
This is what the customer will see on the checkout page:
Matching Shopify metafields to Emarsys custom fields
In order to enhance segmentation and personalization, you can match the metafields in Shopify to Emarsys custom fields under Customizable matching.
For more information on limitations related to field matching and data synchronization, see Field matching and data synchronization.
A typical use case for using custom fields is, for example, when you would like to add customer preferences to your contact data, such as favorite color, size or favorite brand.
- If you need any further assistance, please either raise a Support ticket or contact your Client Success Manager.
- You have to wait until all your customers are uploaded to Emarsys before you can start uploading your Shopify events, products and orders, or install our web behavior tracking scripts. This may take up to a few hours, depending on the size of your customer database.
Here is what you need to do to match Shopify metafields to Emarsys custom fields:
- You need to create the metafields in Shopify on the Settings > Custom Data > Customers page. For more information, please refer to the Shopify documentation.
- After creating metafields, you can match them with Emarsys custom fields on the Shopify Plugin Settings > Field matching page.
In the case of metafields, the first line must contain the namespace of the field (where the field was added), for example:
custom. You need to specify the name of the field in the line below. The plug-in will merge these data as namespace and key.
- You can check if the field matching is correct on the Plugin Settings > Show Field Matching page.
The value must match with the one displayed in the namespace and key fields when you edit the metafield.
- When you are ready, click Save & Close.
Please note that when you click Save & Close, this dialog will close and we will upload your customers to Emarsys. The time needed for the complete synchronization depends on the size of your customer database.
Field matching and data synchronization
Take the following into consideration when matching fields and synchronizing data from Shopify to Emarsys:
- You can match Shopify fields and metafields to Emarsys text fields without any limitations.
Please note that there are
short text and
long text fields in Emarsys, make sure you choose the right type when matching fields. For more information, see sections Emarsys System Fields and their IDs and E-commerce fields.
- The Emarsys Shopify plug-in supports synchronization of whole and decimal numbers (which are separated by a decimal point), for example:
10.2. Using other formats or characters may result in synchronization and segmentation issues.
- You can only map Shopify date metafields to custom Emarsys date fields (please do not use the Emarsys
date of birthor
birth date of partnerstandard field in this case) by using the following formats:
- YYYY-MM-DD hh:mm
- YYYY-MM-DD hh:mm:ss
- Currently, you cannot map Shopify fields and metafields to Emarsys single- or multiple-choice fields. In this case, match such fields to Emarsys text fields.
Please note that these fields are case sensitive when creating segments.
3. Synchronizing Shopify events (webhooks) to Emarsys in real time
In the Events section, click Enable to make your Shopify events (i.e. user interactions in your store such as customer registration) available in the Emarsys Marketing Platform.
4. Uploading Shopify product data to Emarsys
To turn on the regular upload of your product data to Emarsys, click Enable in the Products section.
With this information at your disposal, you will be able to target specific customer segments on the basis of which products they bought, viewed or left in their shopping carts, or send them tailor-made product recommendations.
- If you need to have a preview of the Emarsys product feed, please contact Emarsys Support.
- The Emarsys Shopify plug-in synchronizes the fields below. Please note that the plug-in does not support product metafields.
5. Uploading Shopify orders to Emarsys
To turn on the regular upload of your orders to Emarsys, click Enable in the Orders section. This information is essential for Emarsys features such as revenue reporting or product affinity models.
- When you enable order sync for the first time, the app will pull the full history of your orders and push it to Emarsys. Please also take the following into consideration when you enable order sync for the first time:
- Refunds are ignored, they are only synchronized during the plug-in real-time and the Smart Insight daily sync processes.
- Email address is the required identifier: orders without email addresses are ignored. This also applies to the plug-in real-time and Smart Insight daily sync processes.
- By default, the
- Consider the following about the
- The Emarsys plug-in for Shopify uses
processed_atas the default date field and syncs it via Flexible Sales Data (all date fields are synchronized as well and can be used for further segmentation by Smart Insight).
- By default, the field
processed_atstores the same date as
created_at; however, you can change the
processed_atfield in your Shopify store (while
created_atalways refers to the time when Shopify registered the order the first time and it can't be modified).
- You can set the
processed_atfield to any date which is used when migrating from another e-commerce platform to Shopify during the sales history import.
- When you migrate to Shopify and import the sales history, the Smart Insight mapping will automatically refer to the correct date when the order was created.
- The Emarsys plug-in for Shopify uses
6. Setting up Web behavior tracking
Our Web Extend scripts track visitor interactions on your website and process this information to serve validated data to various Emarsys applications, such as Smart Insight, Predict, Interactions or the Automation Center (as Web behavior segments). The app will install them automatically for you.
Please consider the following:
- Product data synchronization:
Web behavior tracking relies on the product catalog that has to be synchronized to Emarsys in a specific way. As the Emarsys Shopify plug-in synchronizes product data in the expected format and structure, we strongly recommend that you activate the plug-in's Web behavior tracking along with product data synchronization only.
If you activate Web behavior tracking without synchronizing the product data, then you need to integrate your product catalog by ensuring that its structure is appropriate. Please note that Emarsys cannot be held responsible for the consequences resulting from such cases.
- Using a theme without a checkout page:
If you implemented a theme that does not include a checkout page, then the default Shopify checkout page will be used. Please note that the Web Extend data collection scripts cannot be injected in this case.
The Emarsys plug-in installs the Web Extend data collection scripts on your website once. After making changes, you have to install the scripts again.
If you are not a Shopify Plus customer, you will need to manually implement the Web Extend data collection scripts into the code of your checkout page as standard Shopify packages do not allow users to modify the template of the checkout page.
To add the script to the page, log in to your Shopify admin, go to Settings > Checkout > Additional Scripts, copy the following code and paste it into the text box:
- You can always test the data collection scripts on a test theme that is not live in your web store.
- Whenever you start using a new theme, make sure you add the scripts to it.
- Currently, the dashboard does not give any indication of whether the scripts are already installed on the listed themes. Please keep track of which theme already has them. But do not worry; you cannot break the integration if you add the scripts to a theme which already has them.
The placeholders in the code snippet below should be replaced as follows:
- #MERCHANT_ID# - Replace this placeholder with your Predict Merchant ID. You can find your Merchant ID on the Predict Data Sources page.
- #CONTACT_IDENTIFIER# - Replace this placeholder with email or in rare cases, with ID depending on whether you use the Shopify (customer) ID or the email address as the external identifier for contacts.
- #SET_CONTACT_IDENTIFIER# - Replace this placeholder with setEmail if the external ID (please see #CONTACT_IDENTIFIER#) is the email address or with setCustomerId if the external ID is Shopify (customer) ID.