Shopify

Overview

The Shopify integration allows you to connect your Shopify store to your Cordial account for seamless exporting of customer, product and order data.

Once the integration is set up, attributes mapped and data synchronized, you will be able to build audiences, trigger messages and personalize message content based on products, customers and order data from your Shopify account.

Install and Setup

Before installing the Cordial app and setting up your API and account keys, ensure that Shopify customer fields you wish to map already have corresponding contact attributes in your Cordial account.

1. Navigate to https://shopify-integration.cordial.com and enter your Shopify shop URL to install the Cordial app.
   
2. Give permission to install the app in your account.
   

Enter your API and account keys

1. In your Cordial account, create a new API key for the catch-all IP address 0.0.0.0/0. Learn how to generate an API key.
2. While in your Cordial account, locate the Cordial Account Key for use in the next step. You can find your account key on the Account Settings page.
3. On the Cordial Administration page in Shopify, enter your API and account keys. Click Test to check the API connection between Cordial and Shopify.
   

Install the JavaScript listener

Installing the JavaScript listener enables Shopify to post data to your Cordial account. The posted data consists of custom events, cart items and orders.

The following custom events and related properties will be available once the JavaScript listener is installed:

Custom events (browse, cart, and order) can not be renamed.

To install the JavaScript listener, click the Install JS Listener button located in the Quick Actions menu on the Cordial Administration page.

You can Edit the JavaScript base script to modify script parameters depending on your store configuration.

If you are using a vanity domain with JavaScript listener v1, add it as the data-cordial-url and t.src value to replace the default track.cordial.io entries.

If you are using vanity domains with JavaScript listener v2, replace the track.v2.js file path with your data vanity domain (typically d.{subdomain}.{domain}.com) as well as the value for trackURL with your site events URL (typically se.{subdomain}.{domain}.com). This so that the JavaScript listener configurations on your website and within the Cordial Shopify app match, and all relevant events and revenue attribution are being tracked.

If you are using JavaScript listener v2 and customizing the JS base script in any way, such as using vanity domains, you will need to take the additional step of calling the matching Shopify initialization script after trackv2.js is loaded. This is done by updating the default cordialShopifyInit() function, which loads the v1 initialization, to load cordialShopifyInit(2) instead:

window.cordialLoaded = function() {
 cordialShopifyInit(2);
}

Map Attributes to Cordial

Once the Cordial app is connected, and the necessary contact attributes created in your Cordial account, you can start mapping Shopify customer fields to your contact attributes in Cordial.

Order and product attributes that are unique to Shopify and do not exist in Cordial will be stored as additional properties of the respective Cordial order or product data collections.

1. Navigate to the Key Mapping page from the Main Menu dropdown in the top right of the Cordial Administration page.
   
2. Add a mapping row for each contact attribute mapping you wish to create. The form fields will preload with available Shopify customer fields and Cordial attributes.
   
   
   Note: It is possible to create and save attribute mappings even when your Cordial merchant credentials are not configured. However, the attribute form fields will not automatically retrieve the available data without a valid connection between the two platforms.
3. You can Test your key mappings to check for errors.
4. Click Save once all Shopify customer fields are mapped to their corresponding Cordial contact attributes.

Note: The Reset button will reset all key mappings for first name, email and subscribed status fields to their default values.

Map to array attributes

You can map Shopify customer fields to array type contact attributes in Cordial using the split(,) array modifier.

For example, to map the Shopify customer tags field to the Cordial tags contact attribute, use tags|split(,) within the Shopify key mapping field. Shopify customer tags will be inserted as an array into the Cordial tags contact attribute.

Map to geo-location attributes

You can map Shopify address customer fields to geo-location type contact attributes in Cordial using the geo modifier.

For example, to map the Shopify customer default_address field to the Cordial address  geo-location contact attribute, use default_address|geo within the Shopify key mapping field. The Cordial geo-location attribute key will vary depending on your geo-location attribute setup in Cordial.

The following address fields are synchronized automatically for every unique geo-location mapping when you Test or Save the mapping:

Synchronize Product, Customer and Order Data

When synchronizing data from Shopify to Cordial, there are two options: manual synchronization and automated recurring synchronization. Normally, you would use the manual method to perform a one-time synchronization of historical data, and then set a recurring schedule for all future automated data posts. Note that these data synchronizations use API calls to post data.

Synchronization is a One-Way Post

Note that synchronization is a one-way post of contact, product and order data. Data is posted from Shopify to Cordial and not in reverse. For example, if a contact attribute is updated in Cordial (i.e. first name), it will not be updated in Shopify.

Synchronizing Subscribe Status

The synchronization of subscribe status changes depending on the contact's status in Cordial. Shopify key for email subscribe status is accepts_marketing: yes/no, which is mapped to Cordial's email subscribe status key of channels.email.subscribeStatus: subscribed/unsubscribed.

The table below displays how subscribe status is updated after synchronization:

Note above that if a contact has unsubscribed from receiving promotional emails in Cordial, it is not possible to change the subscribe status to subscribed as a result of a Shopify synchronization. Also, if a contact is subscribed in Cordial, it is not possible to change subscribe status to none as a result of a Shopify synchronization.

Manually synchronize historical data

After mapping attributes to your Cordial account, you should synchronize all desired historical data from Shopify. This will ensure that your Cordial account is up to date with product, customer and order data from your Shopify account.

Navigate to the Cordial Admin page from the Main Menu dropdown.

On the Cordial Administration page, locate the Jobs section and click Run Now for the desired data collections under the Sync All heading. Doing so will synchronize all historical data in the selected collection, regardless of creation date.

Order Metafields

Shopify allows the ability to store meta data associated with orders. By default, these metafields are not included in the order object. Cordial's integration will automatically check for metafields and sync the data to the orders collection in your account. You can access the data in Smarty or via the API.

In the following example, all of the key value pairs are organized by namespace (as it is saved in Shopify) and all data is formatted accordingly as a string, integer, or a JSON object

{
  "orderID": "12345",
    "properties": {
      "metafields": {
        "inventory": {
          "warehouse": 232,
          "warehouseString": "This is a string value"
        },
      "shipping": {
        "additionalshippingdata": {
        "address": "123 Test Street",
        "city": "San Diego"
      }
    }
   }
  }
}

Notes:

1. The metafields are not searchable within Audience Builder.

2. Only new orders or order updated since the release on Feb 2, 2021 will have this field on the order.

Product Metafields

Like order metafields, products in Shopify can also have meta data associated with them. Most notably are the "SEO Title" and "SEO Description" fields which are provided by Shopify. You can find these like properties on the product in Cordial under the properties key and they'll be grouped by namespace.

Note: Only the global and cordial namespaces will be synced. You can put anything you want into the cordial namespace, however, the value must not contain script tags. All other keys will be ignored.

{
  "productID": "1234ABC",
  "properties": {
    "metafields": [
      {
        "global": {
          "title_tag": "This is the title",
          "description_tag": "This is the description"
        }
      },
      {
        "cordial": {
          "anykey": "any value
        }
      }
    ]
  }
}

Automatically Synchronize Data on a Recurring Schedule

Once you have manually synchronized your data, you can set a recurring interval to automatically synchronize any new and updated data moving forward.

In the Jobs section of the main Cordial Administration page, enter the recurring synchronization interval in minutes (2 minute minimum) for each data collection and click Enable. To disable a running synchronization, click the corresponding Enabled button.

Check for synchronization errors

API call errors can cause data not to post successfully to your Cordial account. Navigate to the Job Logs page where API errors will be listed, along with past synchronization jobs.

The Job Logs page will list the last 100 jobs. Use the Refresh button in case your recent jobs are not listed immediately. In-progress jobs can be canceled by pressing the ✖ button in the Actions column.

Your Shopify account is now configured and synchronized with your Cordial account. You'll now be able to build audiences and trigger messages based on data collected from your Shopify store.

Fulfillment Status Messaging

Leverage your existing Cordial message automation and Podium workflows to trigger email and SMS messages based on the shipment status of your Shopify orders. Messages can be triggered using available Shopify shipment status events as they occur throughout the fulfillment process.

Prerequisites:

• You must have a Shopify Plus merchant account.
• At least one fulfillment service provider is active and selected to fulfill your Shopify products.
• Fulfillment events will be passed to Cordial automatically for each fulfillment service provider without any additional setup.

A unique fulfillment event is created for every Shopify item or order you mark as fulfilled. Orders where product fulfillment is split, for example between an international fulfillment service and a domestic one, will generate two fulfillment events. This allows you to keep customers updated on the status of each individual fulfillment within the same order as products progress through the shipping process.

Trigger messages and build audiences (shipment status)

You can use shipment status events of a fulfillment to trigger messages and create audiences.

• When enabling event triggered sending, choose Custom Event as the trigger and select fulfillment as the custom event. Select shipment_status as the conditional event property and enter the desired shipment status.
• Using audience builder, choose the Custom Event rule and select fulfillment from the tracked event behavior dropdown menu. Select shipment_status as the conditional event property and enter the desired shipment status.

Commonly used shipment status events

The following shipment status events are commonly used to trigger message notifications.

For additional fulfillment event properties, please reference the Shopify fulfillment properties page.

Order Status Messaging

Similar to fulfillment status messaging, you can create audiences and trigger messages in response to Shopify order status events.

Prerequisites: 

• You must have a Shopify Plus merchant account.

Supported order status events:

Trigger messages and build audiences (order status)

You can use order status events to trigger messages and create audiences.

• When enabling event triggered sending, choose Custom Event as the trigger and for the custom event enter one of the three order status events: new_order, refund_order, or cancel_order.
• Using audience builder, choose the Custom Event rule and for the tracked event behavior enter one of the three order status events: new_order, shopifyrefund, or shopifycancel.

Cart Abandonment Flow

{
  "recoverUrl": "url_for_client_to_get_back_to_complete_order",
  "total_discounts": 111, (number)
  "total_line_items_price": 111, (number)
  "total_price": 111, (number)
  "total_tax": 111, (number)
  "items": [
    {
      "product_id": "11111",
      "quantity": 2,
      "variant_id": "var_id_here"
    },
    ...
  ]
}