The Shopify + Iterable integrations lets you automate your multi-channel marketing strategy based on user actions in your Shopify e-commerce website. Simply drop your Iterable API key into the Iterable Shopify app to boost retention and ROI with campaign strategies like cart abandonment and repeat purchase.
TIP
Running your Shopify store in a headless configuration? Ask your Iterable CSM to connect you to a Solutions Architect to understand how the Shopify integration can work with your custom store.
In this article
- Overview
- How it works
- Installation
- Tracked Events
- Purchase attribution
- Event payload examples
- "Headless" or custom front-end Shopify stores
-
Iterable integration FAQs
- Can extra data be added to purchase events?
- Can we change the API key the app is using to connect to Iterable?
- We use Iterable to send order confirmation messages after a purchase, how should we construct our journey trigger to ensure we only message the user once (and not during purchase event updates)?
- Will the Shopify integration populate the userId user profile field?
Overview
This guide walks through the setup and usage of Iterable's Shopify app, expected event types and payloads, and best practices when connecting Shopify with your Iterable project.
Once enabled, the app sends customer details, on-site actions (cart updates, purchases, product views), and product information to your Iterable project, in real time.
How it works
Iterable's Shopify app is a fully managed data integration. The integration uses a combination of Shopify's APIs, Shopify's webhooks, and JavaScript (loaded on the pages of a shop's storefront) to send customer, event, and product data into Iterable.
- Front-end JavaScript is loaded remotely through a Shopify ScriptTag, and is responsible for tracking site-side interactions and attribution data in purchase events.
- Shopify's webhooks notify Iterable about particular events in a shop. For example, when a customer's record is updated in Shopify, a webhook notifies Iterable, updates their user profile.
- Shopify's APIs are used to enrich webhook payloads with supplemental product data, and to perform historical backfills of data during the installation of the app.
Installation
Install the Iterable app from the Shopify App Store (available here).
Read and accept the required permissions of the app.
-
Input a server-side API key from the Iterable project to which you'd like the Shopify app to connect, as well as an email address (only used once, to notify you of the backfill's completion).
Perform an optional, one-time backfill of customer and order data. To perform the backfill, see the Historical backfill section. To skip this step, leave both Customers and Orders options unchecked, and click Next.
-
The admin screen allows you to control what events are sent to your Iterable project. For a detailed explanation of each option, reference the Tracked Events section.
Optionally, copy the snippet of liquid code and add it to your store's theme. This snippet enables the integration to more accurately identify a user when ktracking logins, logouts and product views. For assistance editing your store's theme code, see Shopify's Editing theme code documentation.
Actions tracked within Shopify will now begin flowing to your Iterable project!
Historical backfill
Perform an optional, one-time backfill of customer and order data.
WARNING
- Events, even if backdated, can trigger journeys. Exercise caution if your Iterable project has journeys constructed that are triggered by user updates or purchases.
- Historical backfilling can result in events being overwritten in your Iterable project.
Select Customers to sync customer records, created after the specified date, from your Shopify store to your Iterable project. This can also create or update users.
Select Orders to sync customer purchases, created after the specified date, from your Shopify store to your Iterable project. (This can also create or update users.) Additionally, if any purchases in your project share an order ID with any backfilled purchases from Shopify, they may be updated. NOTE: Only orders made within the last 60 days can be backfilled.
Select a date from which to start the backfill, or leave both Customer and Order unchecked to continue without backfilling.
After the historical backfill has finished, the email address entered in the previous step will receive a count of all synced customers and historical orders.
NOTE
Events synced to Iterable via a historical backfill will contain the field
historical_backfill
set to true
.
Installation verification
After installing the app, it's a good idea to verify whether the front-end JavaScript loads on your store. To verify the JavaScript installation, view the page source of your store and look for a script tag similar to:
<script type="text/javascript" async="" src="https://prod-configuration-app.spiral.world/app/script?shop=example.myshopify.com"> </script>
Tracked Events
Iterable's Shopify app can create and update user profiles, track user actions such as product views, cart updates and purchases, and sync your store's product inventory with Iterable's catalog.
The app's admin screen allows customers to pick and choose which events they'd like to send to Iterable. The following provides an explanation of the types of events the app tracks, the events each checkbox option is responsible for, and detailed information like event payloads, user profile field mappings, and important notes about expected behavior of events.
Events tracked by the integration can be categorized in three ways: Behavioral, Commerce, and Product.
Behavioral events
Behavioral events are tracked site-side with JavaScript written to the storefront by Iterable's connector. Iterable's Shopify app can send the following behavioral events to Iterable:
Event name | Description |
---|---|
login | Created when a user logs in to your store |
logout | Created when a user logs out of your store |
productView | Created when a user views a product |
Commerce events
Commerce events are composed of order, shipping, and customer events.
Order events
Order events are tracked during the checkout, order, draft order, and refund processes. The Order checkbox is responsible for the following events:
Event name | Description |
---|---|
purchase | Created when an order is created in Shopify |
updateCart | Created when a Shopify cart is created or updated |
createCheckout | Created when a checkout is created or updated in Shopify |
createDraftOrder | Created when a draft order is created or updated in Shopify |
cancelOrder | Created when order has been cancelled in Shopify |
createRefund | Created when a refund is issued in Shopify |
NOTE
Purchase events can be updated after the initial purchase date.
When a purchase order is updated in Shopify, the purchase will be updated in
Iterable. To understand when an order has been updated, we've included a boolean
field in the purchase payload called update
. The initial purchase tracked in
Iterable will have update: false
. Subsequent updates to a purchase will have
update: true
.
Shipping events
After an order has been placed, details about order fulfillment can be sent to Iterable. For example, the following events can be used to message customers about their purchase being fulfilled, shipped, and delivered.
The Shipping checkbox is responsible for the following:
When a fulfillment is created on an order in your Shopify Store, Iterable's Shopify app will send a
createFulfillment
event to Iterable.-
When a fulfillment is updated on an order in your Shopify Store, Iterable's Shopify app will update the associated
purchase
event with afulfillment_status
. Possible values for this field include:-
pending
: The fulfillment is pending. -
open
: The fulfillment has been acknowledged by the service and being processed. -
success
: The fulfillment was successful. -
cancelled
: The fulfillment was cancelled. -
error
: There was an error with the fulfillment request. -
failure
: The fulfillment request failed.
Specific fulfillment events are also relayed to Iterable. The name of the event is dependent on the
status
field included in the fulfillment event payload from Shopify. Depending on the status, here are the resulting events:Fulfillment status Iterable event confirmed
orderShippingConfirmed
in_transit
orderInTransit
out_for_delivery
orderOutForDelivery
delivered
orderDelivered
failure
orderDeliveryFailure
attempted_delivery
orderAttemptedDelivery
label_printed
orderLabelPrinted
label_purchased
orderLabelPurchased
ready_for_pickup
orderReadyForPickup
-
NOTE
Fulfillment and FulfillmentEvents are treated as separate events in Shopify.
Customer events
A customer profile is created when a customer interacts with your business. For example, a profile is created when a customer:
- Signs up for your mailing list or a customer account.
- Places an order.
- Starts an order, but abandons their checkout.
- Is added to your customer list manually.
Whenever a customer is created, updated, or enabled/disabled in Shopify, their user profile is updated in Iterable. These are the fields that can be synced from a Shopify customer record to Iterable:
Field name | Type | Description |
---|---|---|
accepts_marketing * | Boolean | Whether or not the customer has consented to receive marketing material via email. |
addresses | Array | A list of the customer's ten most recently updated addresses. |
default_address | Object | The customer's default address. |
email_marketing_consent | Object | Information collected by Shopify when the customer agreed to receiving marketing information by email. |
first_name | String | The customer's first name. |
id | String | A unique identifier for the customer. Shopify's id field maps to Iterable's userId field. |
last_name | String | The customer's last name. |
note | String | A note about the customer. |
orders_count | Long | The number of orders associated with this customer |
phone_number | String | The unique phone number for this customer. |
shopify_created_at | Date | The date and time when the customer was created. |
shopify_updated_at | Date | The date and time when the customer information was last updated. |
sms_marketing_consent | Object | Information collected by Shopify when the customer agreed to receiving marketing information by SMS. |
state | String | The state of the customer's account with a shop. |
tags | String | Tags that the shop owner has attached to the customer, formatted as a string of comma-separated values. |
tax_exempt | Boolean | Whether the customer is exempt from paying taxes on their order. |
total_spent | Long | The total amount of money that the customer has spent across their order history. |
NOTE
Shopify has deprecated the accepts_marketing
field in favor of the
email_marketing_consent
and sms_marketing_consent
fields. These fields do
not directly affect a user's subscription preferences in Iterable, but they
can be used to update those preferences (for example, in a journey). If you have
questions about how to use these fields, talk to your Iterable CSM or check out
Shopify's documentation.
WARNING
If you have Enable IP to Location Lookup
enabled in your Iterable project settings, or if you presently use a state
field on
the user profile, the state
field will overwritten by Shopify's state
value.
There are two common ways to address this problem:
- Use a different field name to contain the state value. For example, use
postalState
to store a user postal address state. - Nest the state field under a different property on the user profile. For example,
postalAddress.state
.
For more information about user fields, see Shopify's documentation about the Customer Object.
Product tracking
NOTE
This feature requires a Catalog subscription. Contact your Iterable customer success manager to discuss adding Catalog to your plan.
The selection of Catalog (under Product Tracking) on the admin screen will
prompt Iterable’s Shopify app to sync data to a catalog called shopifyCatalog
.
shopifyCatalog
will be kept up-to-date with the latest product information
when they are updated in Shopify. When first enabled, a date picker will appear.
All products created after the inputted date will be synced to your
shopifyCatalog
.
The shopifyCatalog
will contain the following fields:
Catalog field | Description |
---|---|
id | The unique numeric identifier for the product variant. |
url | A link to the product. |
sku | A unique identifier for the product variant in the shop. |
name | The name of the product variant. |
price | The price of the product variant. |
status | The status of the product. |
handle | A unique human-friendly string for the product. |
vendor | The name of the product's vendor. |
discount | The difference between the compare_at_price and the price . |
imageUrl | The URL image of the product variant. |
inventory | An aggregate of inventory across all locations. |
published | Boolean dependent on whether or not the product is published. |
categories | Tags (separated by commas) for searching and filtering products. |
product_id | The unique numeric identifier for the product. |
description | A description of the product. |
product_type | A categorization for the product used for filtering and searching products. |
inventory_policy | Whether customers are allowed to place an order for the product variant when it's out of stock. Valid values are deny or true . |
compare_at_price | The original price of the item before an adjustment or a sale. |
inventory_quantity | An aggregate of inventory across all locations. |
inventory_management | The fulfillment service that tracks the number of items in stock for the product variant. |
sales_channels_and_apps | Whether the product is published to the Point of Sale channel. Valid values are web and global . |
Purchase attribution
Iterable's Shopify integration is capable of attributing purchases back to Iterable campaigns and templates through two methods:
Iterable cookies: Iterable's
iterableEmailCampaignId
anditerableTemplateId
cookie values are included in purchase events to enable campaign and template attribution. For more information about this feature, see Tracking Purchases and Revenue for more information about setting up this featureURL parameters: When
iterable_campaign
oriterable_template
(case insensitive) are present in the URL bar when a user visits your store, the integration will include those values as thecampaignId
andtemplateId
in purchases events.
NOTE
If both cookies and URL parameters are present, the URL parameter values will take precedence.
Event payload examples
Below are examples of what an event in Iterable might look like when sent from the app.
Cart update
{ "email":"shopifyTestUser@email.com", "eventName": "updateCart", "eventType": "customEvent", "shoppingCartItems":[ { "id":"18998762807461", "price":9, "quantity":1, "key":"18998762807461:87f0fe531569cd439f2f63cc68213948", "sku":"ite1", "url":"https://example.myshopify.com/products/margherita-pizza", "name":"Margherita Pizza", "imageUrl":"https://cdn.shopify.com/s/files/1/0574/7366/3153/products/Pizza_Margherita.jpg?v=1622678940", "grams":0, "taxable":false, "gift_card":false, "vendor":"example", "product_id":"2796811046353", "variant_id":"18998762807461", "shopify_store_domain":"example.myshopify.com", "original_price":9, "line_price":9, "total_discount":0, "discounted_price":9, "original_line_price":9, "description":"Pizza Margherita (more commonly known in English as Margherita pizza) is a typical Neapolitan pizza, made with San Marzano tomatoes, mozzarella cheese, fresh basil, salt and extra-virgin olive oil." } ] }
Purchase
{ "id":"4492994576561", "shoppingCartItems":[ { "id":"11536696770737", "price":9, "quantity":1, "sku":"ite1", "url":"https://example.myshopify.com/products/margherita-pizza", "name":"Margherita Pizza", "imageUrl":"https://cdn.shopify.com/s/files/1/0574/7366/3153/products/Pizza_Margherita.jpg?v=1622678940", "variant_title":"", "vendor":"example", "fulfillment_service":"manual", "variant_inventory_management":"shopify", "product_id":"2796811046353", "requires_shipping":false, "taxable":false, "gift_card":false, "variant_id":"18998762807461", "properties":[ ], "product_exists":true, "fulfillable_quantity":10, "grams":0, "total_discount":0, "fulfillment_status":"fulfilled", "admin_graphql_api_id":"gid://shopify/LineItem/11536696770737", "description":"Pizza Margherita (more commonly known in English as Margherita pizza) is a typical Neapolitan pizza, made with San Marzano tomatoes, mozzarella cheese, fresh basil, salt and extra-virgin olive oil." } ], "createdAt":"2022-05-20T22:07:52.000Z", "email":"shopifyTestUser@email.com", "taxes_included":false, "currency":"USD", "buyer_accepts_marketing":false, "name":"#1121", "customer_locale":"en-US", "app_id":"580111", "order_number":"1121", "payment_gateway_names":[ "shopify_payments" ], "note_attributes": { "authenticPizza": true }, "fulfillment_status":"fulfilled", "contact_email":"shopifyTestUser@email.com", "order_status_url":"https://example.myshopify.com/34322680223/orders/vfk69pxjz17yh52nicgivfk69pxjz17y/authenticate?key=ihlaqq34l0enl4hzy23uys5i0rw3ijrw", "billing_address":{ "first_name":"foo", "last_name":"bar", "address1":"123 Main Street", "address2":"", "city":"San Francisco", "province":"California", "country":"United States", "zip":"94105", "name":"foo bar", "province_code":"CA", "country_code":"US", "latitude":37.7749, "longitude":-122.4194 }, "fulfillments":[ { "id":"9322221615472", "order_id":"6771501407078", "status":"success", "created_at":"2022-05-20 16:07:54 -06:00", "updated_at":"2022-05-20 16:07:54 -06:00", "service":"manual", "location_id":"22305121296", "receipt":{ }, "name":"#1121.1" } ], "payment_details":{ "credit_card_bin":"424242", "avs_result_code":"Y", "cvv_result_code":"M", "credit_card_number":"•••• •••• •••• 4242", "credit_card_company":"Visa" }, "total":9, "totals":{ "total_price_usd":9, "total_discounts":0, "total_line_items_price":9, "total_price":9, "total_tax":0, "total_weight":0, "subtotal_price":9 }, "misc":{ "number":"121", "test":true, "admin_graphql_api_id":"gid://shopify/Order/4492994576561", "confirmed":true, "financial_status":"paid", "processing_method":"direct", "checkout_id":"29789212489387", "browser_ip":"127.0.0.1", "source_name":"web" }, "update":false }
"Headless" or custom front-end Shopify stores
It's crucial that your store loads the app's JavaScript on all store pages (aside from checkout). If you're using a custom front-end for your store that prevents Iterable's app from using a ScriptTag, the script can be manually installed by your developers.
Install the following in the <head>
of all of your store's pages:
<script type="text/JavaScript" async="" src="https://prod-configuration-app.spiral.world/app/script?shop=<YOUR_STORE_DOMAIN>"> </script>
(Replace <YOUR_STORE_DOMAIN>
with the name of your Shopify-managed domain. For
example, iterable.myshopify.com
.)
Once installed, perform an Installation verification to ensure it's working as expected.
Iterable integration FAQs
Can extra data be added to purchase events?
Yes, custom attributes included in Shopify's cart are mapped to the
note_attributes
field in purchase events. For more information on how to
utilize this field, see Shopify's cart.attributes
documentation.
Can we change the API key the app is using to connect to Iterable?
Yes, paste a new API key in the "Iterable API Key" section of the app's admin screen and select "Update" to have the new key take effect.
We use Iterable to send order confirmation messages after a purchase, how should we construct our journey trigger to ensure we only message the user once (and not during purchase event updates)?
In your journey entrance trigger, set the entry rules to only allow purchases
where update
equals false
. When is a purchase is updated, update
becomes
true
. This trigger filter will ensure the journey only allows a user to
enter if this is their initial purchase.
userId
user profile field?
Will the Shopify integration populate the Yes, Shopify's customerId
maps to Iterable's userId
. Existing Iterable
userId
values will be overwritten by incoming Shopify customerId
values.
Comments
0 comments
Please sign in to leave a comment.