Integration:: Emarsys plug-in for Shopify - Integration Manual – Emarsys

Prerequisites

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.

Notes:

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_ignore tag to the specific contact in your Shopify store. Please consider the following:
- Contacts with the emarsys_ingore tag 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_ignore tag may be created with just an email address (without any opt-in data) in order to send transactional messages to them.
- The emarsys_ignore tag 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.

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

Notes:

Currently, only the email address identifier 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 email identifier that can be switched to Shopify ID.

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.

Notes:

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 email field will be used as the external key to match with your Emarsys contacts. Please note that the Shopify ID field 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 Created At and Updated At Shopify standard date fields:
- These fields are mapped and synced automatically to Emarsys:
  - Created At -> Shopify Created At
  - Updated 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 At instead of the field date of registration (i.e. the date when contacts were created) especially in the Smart Insight Settings.

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.

Notes:

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 Consent field 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.

Use case:

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.

Notes:

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 or 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 birth or birth date of partner standard field in this case) by using the following formats:
- YYYY-MM-DD
- 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.

Notes:

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.
- title
- item
- link
- image
- category
- description
- price
- msrp
- available
- brand
- group_id
- zoom_image
- c_qty
- c_tags

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.

Notes:

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 email field will be used as the external key to match with your Emarsys contacts.
Consider the following about the processed_at field:
- The Emarsys plug-in for Shopify uses processed_at as 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_at stores the same date as created_at; however, you can change the processed_at field in your Shopify store (while created_at always refers to the time when Shopify registered the order the first time and it can't be modified).
- You can set the processed_at field 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.

Please take the following into consideration if you are using Smart Insight:

If Smart Insight is activated in your account, then you do not need to regularly upload your orders to Emarsys.
If you upload sales data into Smart Insight via the Emarsys Shopify plug-in, select the Upload via Plugin option when you configure your sales data. For more information, see Configuring your sales data.
If you start using the Emarsys Shopify plug-in after 10 March, 2021, then the Upload via Plugin option is selected in Smart Insight during the initial implementation and you don't need to upload sales sample data.
If you have recently activated the Emarsys Shopify plug-in, then you need to wait 1-3 hours until the Smart Insight mappings are available.
Order data does not contain taxes when it is synchronized to Smart Insight. Emarsys changed the sales data processing method on 10 March 2021, as a result, Emarsys synchronizes order data including all details (i.e. the price with and without tax and the delivery cost) and Smart Insight calculations use gross values. If it is required, you can set further purchase filters on the Smart Insight settings page.
The Emarsys Shopify plug-in uses exclusively the email identifier, even though the Smart Insight Self-Service tool shows that ems_user_id (internal emarsys ID) is used for identification. The plug-in transforms email into ems_user_id during synchronization to avoid storing personal data on the data platform.
Emarsys retrieves all available sales data attributes from your Shopify store. The mandatory fields are pre-mapped and cannot be changed. You can decide which of these attributes you would like to use for further segmentation and filtering.
To successfully reload your sales data, when using the Shopify plug-in, please contact Emarsys Support first.

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:

Notes:

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.

Code snippet

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.

<script type="text/javascript" id="scarab-queue">
  var ScarabQueue = ScarabQueue || [];
  (function(id) {
    if (document.getElementById(id)) return;
    var js = document.createElement('script'); js.id = id;
    js.src = '//cdn.scarabresearch.com/js/#MERCHANT_ID#/scarab-v2.js';
    var fs = document.getElementsByTagName('script')[0];
    fs.parentNode.insertBefore(js, fs);
  })('scarab-js-api');
</script>
<script id="scarab-cart">
  var cartItems = [];
  {% if checkout.line_items %}
    if (Shopify && Shopify.Checkout && Shopify.Checkout.step !== 'thank_you') {
      cartItems = [
        {% for item in checkout.line_items %}
          {item: '{{item.variant_id}}', price: {{ item.line_price | divided_by: 100.00 }}, quantity: {{item.quantity}}}{% if forloop.last == false %},{% endif %}
        {% endfor %}
      ];
    }
  {% else %}
    {% if cart.items %}
      cartItems = [
        {% for item in cart.items %}
          {item: '{{item.variant_id}}', price: {{ item.line_price | divided_by: 100.00 }}, quantity: {{item.quantity}}}{% if forloop.last == false %},{% endif %}
        {% endfor %}
      ];
    {% endif %}
  {% endif %}
  ScarabQueue.push(['cart', cartItems]);
</script>
<script type="text/javascript" id="scarab-purchase">
  {% if checkout.order.financial_status == 'paid' or checkout.order.financial_status == 'authorized' %}
  (function() {
    {% assign orderTotalNum = checkout.subtotal_price | plus: checkout.discounts_amount %}
    {% assign orderTotalNumFloat = orderTotalNum | times: 1.0 %}
    {% assign discountPerc = checkout.discounts_amount | divided_by: orderTotalNumFloat | times: 100.0 %}
    {% assign orderCreatedAt = checkout.order.created_at | date: '%s' %}
    {% assign nowTimestamp = 'now' | date: '%s' %}
    {% assign orderAge = nowTimestamp | minus: orderCreatedAt %}
    var orderStorageKey = "scarab_order_number";
    var orderAgeTimeLimit = 20;
    if ({{ orderAge }} < orderAgeTimeLimit && !hasOrderSent({{ checkout.order_number }})) {
      ScarabQueue.push(['purchase', {
        orderId: {{ checkout.order_id }},
        items: [
          {% for item in checkout.line_items %}
            {% assign discountLineItem = item.line_price | times: discountPerc | divided_by: 100.0 | round: 2 %}
            {item: {{item.variant_id}}, price: {{ item.line_price | minus: discountLineItem | divided_by: 100.0 }}, quantity: {{item.quantity}}}{% if forloop.last == false %},{% endif %}
          {% endfor %}
        ]
      }]);
      setOrderSent({{checkout.order_number}});
    }
    function hasOrderSent(orderId) {
      return localStorage.getItem(orderStorageKey) >= orderId;
    };
    function setOrderSent(orderId) {
      localStorage.setItem(orderStorageKey, orderId);
    }
  })();
  {% endif %}
</script>
<script id="scarab-go">
  {% if customer.#CONTACT_IDENTIFIER# %}
    ScarabQueue.push(['#SET_CONTACT_IDENTIFIER#','{{customer.#CONTACT_IDENTIFIER#}}']);
  {%else%}
    {% if checkout.customer.#CONTACT_IDENTIFIER# %}
      ScarabQueue.push(['#SET_CONTACT_IDENTIFIER#','{{checkout.customer.#CONTACT_IDENTIFIER#}}']);
    {%endif%}
  {%endif%}
  ScarabQueue.push(['go']);
</script>

Click to copy

Need assistance with your Emarsys product? We'll get you the help you need!

Shopify

Prerequisites

Installing the Emarsys plug-in

Configuring the Emarsys plug-in

1. Connecting your Shopify store to Emarsys

2. Uploading Shopify customer data to Emarsys

Synchronizing SMS opt-in data

Matching Shopify metafields to Emarsys custom fields

Field matching and data synchronization

3. Synchronizing Shopify events (webhooks) to Emarsys in real time

4. Uploading Shopify product data to Emarsys

5. Uploading Shopify orders to Emarsys

6. Setting up Web behavior tracking

Need assistance with your Emarsys product?
We'll get you the help you need!