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.
- Navigate to https://shopify-integration.cordial.com and enter your Shopify shop URL to install the Cordial app.
- Give permission to install the app in your account.
Enter your API and account keys
- 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.
- 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.
- 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 Event Name | Related Properties |
---|---|
browse | url, source, product, category |
cart | url, source, page |
order | source, orderID |
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.
accepts_marketing
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.- Navigate to the Key Mapping page from the Main Menu dropdown in the top right of the Cordial Administration page.
- 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. - You can Test your key mappings to check for errors.
- 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:
Shopify | Cordial |
---|---|
address1 | street_address1 |
address2 | street_address2 |
city | city |
province_code | state |
zip | postal_code |
country_code | country |
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:
Contact exists in Cordial | Subscribe Status in Cordial | Subscribe Status in Shopify | Subscribe Status in Cordial After Synchronization |
---|---|---|---|
No | N/A | Accepts email marketing | Subscribed |
No | N/A | Does not accept email marketing | None |
Yes | None | Accepts email marketing | Subscribed |
Yes | Subscribed | Does not accept email marketing | Subscribed (Subscribe status is not overwritten) |
Yes | Unsubscribed | Accepts email marketing | Unsubscribed (Subscribe status is not overwritten) |
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.
Shipment Status | Description |
---|---|
confirmed | The carrier is aware of the shipment, but hasn't received it yet. |
in_transit | The shipment is being transported between shipping facilities on the way to its destination. |
out_for_delivery | The shipment is being delivered to its final destination. |
attempted_delivery | Delivery of the shipment was attempted, but unable to be completed. |
delivered | The shipment was successfully delivered. |
ready_for_pickup | The shipment is ready for pickup at a shipping depot. |
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:
Order Event | Description |
---|---|
new_order | Shopify order has been created. |
refund_order | Shopify order has been refunded. |
cancel_order | Shopify order has been canceled. |
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
-
When the customer clicks checkout without entering their contact information, a "checkout" object is created within Shopify, but it's not able to use yet as we don't have the customer email.
-
If the customer submits their name and email in the first checkout step, the "checkout" object gets updated with customer details and the object gets sent to Cordial with the event data.
-
If the customer completes the order, Cordial will have an "order" event and object
-
If the order is not completed the "cart abandonment" flow can be initiated by using the event name, "abandoned_cart".
Note: When trying to send messages by the events, they should wait for a min or two and then in the message they should probably check if there was an order after the event above happened. As that means, there was an order after the above abandonment checkout.
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 you'll find there are two properties source and via included in the event data. 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).
Included in every contact activity is a property domain which is helpful in the case where two Shopify stores are connected to a single Cordial account.
Event Name | via | Notes |
browse | tjs | |
shopifycart | tjs | |
order | tjs | |
new_order | api/tjs | Typically if you see an event with an api it means the webhook beat the track JS call (which should be rare). Additionally, if you process an order outside of your website (POS or subscription service) you'll see these events |
login | tjs | Occurs when a contact logs in using a Shopify form or after a contact completes a purchase/order. |
shopifysignup |
tjs | Only occurs when a contact submits a Shopify register (create account form) |
cancel_order | api | |
refund_order | api | |
fulfillment | api | The fulfillment event will be triggered several times. The shipment_status property of the event will change based on Shopify’s values (Shopify docs) |
abandoned_checkout | api | Fired when a contact begins the checkout process filling out their shipping information and then leaving the page (not continuing to payment form) |
Comments
0 comments
Article is closed for comments.