Shopify Integration

Overview

Cordial's integration with Shopify 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—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.

Install and set up

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.

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

2. Give permission to install Cordial in your account.

Enter your API and account keys

1. Log in to Cordial, click the Administration 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 Administration > 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:

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.

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

Use vanity domains with JS listener

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 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 are using JavaScript listener v2 and 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.

1. Log into Shopify and navigate to Main Menu > Cordial Admin > 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.

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.

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.

Map to geo-location attributes

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

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

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.

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

2. On the Cordial Admin 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 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"
      }
    }
   }
  }
}

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.

{
  "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.

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

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

Check for synchronization errors

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

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.

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.

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.

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.

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.

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.

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