Overview

Cordial's Shopify app seamlessly transfers customer, product, and purchase data directly into Cordial. Once the integration is set up—and your attributes are mapped and your data is synchronized—you can build audiences, trigger messages, and personalize message content based on data from your Shopify account, enhancing the shopping experience and increasing revenue.

Install Cordial's Shopify app

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

At least one contact attribute needs to be present in your Cordial account to successfully connect.

1. Navigate to Cordial's app listing in the Shopify app store and click Install.

2. Review the Privacy details and Permission details. 

3. Click the Install app button.

Enter your API and account keys

1. Log in to Cordial, click the Settings dropdown, and select API Keys.

2. Select New on the API Keys page. Create an API key for the catch-all IP address 0.0.0.0/0.

• Learn how to generate an API key here.

3. While in your Cordial account, navigate to Settings > Account Settings and locate the Cordial account key for use in the next step. 

4. Back in Shopify, enter your API and account keys on the Cordial Administration page. 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, shopifycart, and order) cannot be renamed.

Please contact your CSM for assistance when transitioning an existing instance of your Shopify app from JS Listener v1 to v2.

1. To install the JavaScript Listener, log into Shopify and click the Install JS Listener button located in the Quick Actions menu on the Cordial Administration page.

If in the past you manually set up the JS Listener for your Shopify site, you can skip the installation step. Under these circumstances, installing the script using the install button will double the calls for browse, cart, and order events.

2. Select Edit the JavaScript base script to modify script parameters depending on your store configuration.

Use vanity domains with JS Listener

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 will ensure 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're customizing the JS base script in any way, such as using vanity domains, you 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 to your Shopify account—and the necessary contact attributes have been 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.

All available Shopify customer fields should be mapped to Cordial attributes to ensure all data is properly transferred during synchronization. All Cordial attribute mappings must be unique. Mapping the same attribute value more than once is not supported.

The email_marketing_consent.state and email Shopify customer fields will automatically map to Cordial's channels.email.subscribeStatus and channels.email.address contact attributes. You can verify this mapping from the Key Mapping page.

1. Log in to Shopify and navigate Apps > Cordial. Click the Main Menu dropdown and select Key Mapping.

2. Select Add Mapping Row for each contact attribute mapping you wish to create. The form fields will preload with available Shopify customer fields and Cordial attributes.

It's 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. Select Test to check your key mappings for errors.

4. Click Save once all Shopify customer fields are mapped to their corresponding Cordial contact attributes.

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.

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 geolocation attributes

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

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

Automatically synced address fields

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 between Shopify and 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.

Synchronization process

When syncing all of your historical data, Cordial starts by syncing all products and all customers and then moves on to the most recent 90 days of orders. A complete the sync for the rest of your order history will run in the background. You can check the status of that data job by navigating to Main Menu > Job Logs.

These data synchronizations use API calls to post data. Historical synchronization will take longer for large amounts of data.

Shopify contacts without an email address on file will be excluded from synchronization to Cordial. These contacts can be synchronized during the next manual or automated synchronization job after the profile email address has been added in Shopify.

Synchronization is a one-way post

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.

Synchronize subscribe status

The synchronization of subscribe status changes according to the contact's status in Cordial. The Shopify key for email subscribe status is email_marketing_consent.state: subscribed/not_subscribed, 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.

If a contact has unsubscribed from promotional emails in Cordial, it's not possible to change the subscribe status back 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.

When a historical import is started, Cordial immediately imports your products and then begins the process of batch importing your contacts and orders. Cordial queries Shopify for your customers and syncs them one month at a time. Once this is complete, the same process is followed for your orders.

1. Log in to Shopify and navigate Apps > Cordial. Click Admin under the Main Menu dropdown.

2. On the Cordial Administration page, scroll down to Historical Import and click Start Historical Import for the desired data collections.

When syncing all of your historical data, Cordial starts by syncing all products and all customers and then moves on to the most recent 90 days of orders.

3. A complete the sync for the rest of your order history will run in the background. You can check the status of that data job by navigating to Main Menu > Job Logs.

Order metafields

Shopify allows you to store metadata 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 JSON object.

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

The metafields are not searchable within Audience Builder.

Product metafields

Like order metafields, products in Shopify can have metadata associated with them. Most notably are the SEO Title and SEO Description fields provided by Shopify. You can find these like properties on the product in Cordial: under the properties key and grouped by namespace.

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
        }
      }
    ]
  }
}

The Last Sync timestamp is based on the user's local timezone.

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.

1. Log in to Shopify and navigate to Main Menu > Cordial Admin. 

2. In the Recurring Sync Settings pane, enter the recurring synchronization interval in minutes (two-minute minimum) for each data collection and click Enable. To disable a running synchronization, click the corresponding Enabled button.

Historical data will not be synchronized to Cordial when the recurring sync begins. Only new and updated data since the last synchronization will be posted.

Check for synchronization errors

API call errors can cause data not to post successfully to your Cordial account. 

1. Navigate to Main Menu > Job Logs. API errors will be listed along with past synchronization jobs. The Job Logs page will list the last 100 jobs.

2. 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.

The job start and end timestamps are based on the user's local timezone.

3. Once your Shopify account is successfully configured and synchronized with your Cordial account, you can 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

1. You must have a Shopify Plus merchant account.

2. 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.

To avoid sending duplicate messages, contact your Shopify representative to disable shipping notifications.

3. 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.

1. From within your message in Cordial, navigate to Sending Methods > Event Triggered.

2. Choose Custom event as the trigger and select fulfillment as the custom event. Select status as the conditional event property and enter the desired shipment status.

3. Using Audience Builder, choose the Custom Event rule and select fulfillment from the tracked event behavior dropdown menu. Select 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.

Shipment status event names must be entered exactly as shown below.

For additional fulfillment event properties, you can visit 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.

To avoid sending duplicate messages, contact your Shopify rep to disable the Shopify order status notifications.

• Prerequisite: 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.

1. From within your message navigate to Sending Methods > Event Triggered.

2. Choose Custom Event as the trigger and enter one of the three order status events: new_order, refund_order, or cancel_order.

3. Using Audience Builder, choose the Custom Event rule and enter one of the three order status events: new_order, shopifyrefund, or shopifycancel.

Cart abandonment flow

If your customer starts the process of checking out by entering their email and shipping information—and they click the Continue to Payment button but don’t complete the purchase—you can create audiences and trigger messages in response to those abandoned checkout events.

After a customer goes to the checkout page, the checkout object gets created in Shopify. This object will receive updates as the customer continues with the checkout flow. Here are a few scenarios that might play out regarding that data.

Event name: "abandoned_checkout"

Event data:

{
  "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"
    },
    ...
  ]
}

Summary of events

Cordial's Shopify app will create a number of events. For most of the events, there are two properties included in the event data: source and via. The source will always be shopify and via will be either tjs (the Cordial JavaScript Listener) or api (created by a webhook from Shopify or the recurring sync).

Every contact activity includes a property domain, which is helpful if you have two Shopify stores connected to a single Cordial account.