How can we help?

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 upand your attributes are mapped and your data is synchronizedyou 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.

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

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.

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:

Custom Event Name Related Properties
browse url, source, product, category
cart url, source, page
order source, orderID
Note: Custom events (browse, cart, and order) cannot be renamed.

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.

Warning: Please contact your CSM for assistance when transitioning an existing instance of your Shopify app from JS listener v1 to v2.
Warning: 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

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 accountand the necessary contact attributes have been created in your Cordial accountyou 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.

Note: 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.
Tip: 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 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.

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

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.

Use case: 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.

Use case: 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.

Automatically-synced address fields

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

Note: These data synchronizations use API calls to post data.
Note: 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 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: If a contact has unsubscribed from promotional emails in Cordial, it is 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.

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"
}
}
}
}
}
Note: 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.

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
}
}
]
}
}
Note: 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 > 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.

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

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.

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

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.
Warning: To avoid sending duplicate messages, contact your Shopify representative to disable shipping notifications.

A unique fulfillment event is created for every Shopify item or order you mark as fulfilled. Orders where product fulfillment is splitfor example between an international fulfillment service and a domestic onewill 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.

Note: Shipment status event names must be entered exactly as shown below.
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, 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.

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

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.

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 informationand they click the Continue to Payment button but don’t complete the purchaseyou 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.

  • When the customer clicks checkout without entering their contact information, a checkout object is created within Shopifybut it's not usable yet because 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 is 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 with these events, we recommend that you wait for a minute or two, then in the message check if there was an order after the event occurred. If so, 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, 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.

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

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. Learn more in Shopify's 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.