Shopify + Iterable Integration

The Shopify + Iterable integration lets you automate your multi-channel marketing strategy based on user actions in your Shopify e-commerce website. Connect Shopify to Iterable to boost retention and ROI with campaign strategies like cart abandonment and repeat purchase.

# In this article

# Overview

This guide walks through how to set up and use Iterable's Shopify app, expected event types and payloads, and best practices for connecting Shopify with your Iterable project.

Once the integration is set up, 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 and webhooks, and JavaScript (loaded on the pages of a shop's storefront) to send customer, event, and product data to Iterable.

• Front-end JavaScript is loaded remotely through a Shopify ScriptTag and tracks 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 and updates their user profile.
• Shopify's APIs enrich webhook payloads with supplemental product data and perform historical backfills of data during the installation of the app.

# Installation

When possible, we recommend installing the app on a staging version of your store and connecting it to an Iterable sandbox project to become familiar with the expected functionality of the app.

1. Download the Iterable app from the Shopify App Store.

2. Read and accept the required permissions.

3. Enter a server-side API key from the Iterable project you want to connect to Shopify, and an email address (only used once, to notify you of the backfill's completion).

   

4. (Optional) Perform a one-time historical backfill of customer and order data. To skip this step, leave the Customers and Orders options unchecked, and click Next.

5. The admin screen lets you control what events are sent to your Iterable project. For a detailed explanation of each option, see the Tracked Events section.

   

6. (Optional) 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 tracking logins, logouts, and product views. For help editing your store's theme code, see Shopify's Editing theme code support guide.

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.

• 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 Customers and Orders unchecked to continue without backfilling.

After the historical backfill has finished, the email address you entered in the previous step will receive a count of all synced customers and historical orders.

# Verifying the installation

After installing the app, it's a good idea to check 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.integrations-itbl.co/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 lets you choose which events you want to send to Iterable. This section provides an explanation of the types of events the app tracks and information about event payloads, user profile field mappings, and expected behavior of events.

This integration tracks three types of events:

• Behavioral events
• Commerce events
• Product events

# 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:

# Commerce events

There are three types of commerce events:

• Order events
• Shipping events
• 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:

# 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 events:

• When a fulfillment is created on an order in your Shopify Store, Iterable's Shopify app will send a createFulfillment event to Iterable.

• When fulfillments are updated, the fulfillment data in an order is also updated. Iterable's Shopify app will update the associated purchase event with a fulfillment_status. Possible values for this field include:

  • pending: The fulfillment is pending.
  • open: The fulfillment has been acknowledged by the service and is 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

# 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:

For more information about user fields, see Shopify's Customer Object support guide.

# Product tracking

Selecting 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:

# Purchase attribution

Iterable's Shopify integration can attribute purchases back to Iterable campaigns and templates through two methods:

• Iterable cookies: Iterable's iterableEmailCampaignId and iterableTemplateId cookies are included in purchase events to enable campaign and template attribution. For more information read Tracking Conversions, Purchases, and Revenue

• URL parameters: When iterable_campaign or iterable_template (case insensitive) are present in the URL bar when a user visits your store, the integration will include those values as the campaignId and templateId in purchases events.

# Event payload examples

Here are some examples of what an event in Iterable might look like when sent from the app.

# Cart update

{
  "email":"user@example.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":"user@example.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":"user@example.com",
  "order_status_url":"https://example.myshopify.com/34322680223/orders/d43c4d4c44c54cedb56adb0d343b6212/authenticate?key=a0ac882c10a94dce86e1f07262addea3",
  "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
}

# Frequently asked questions

# 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 use this field, see Shopify's cart.attributes support guide.

# Can I change the API key the app is using to connect to Iterable?

Yes. To do this, go to the app's admin screen, and paste a new API key in the Iterable API Key section. Click Update.

# I use Iterable journeys to send users an order confirmation message after they make a purchase. How can I prevent users from receiving multiple order confirmation messages after purchase event updates?

In your journey's Start tile, set the entry rules to only allow purchases where update equals false. (When a purchase is updated, update becomes true.) This entry rule will ensure the journey only allows a user to enter if this is their initial purchase.

# Does this integration populate the userId user profile field?

Yes, Shopify's customer id field maps to Iterable's userId field. Existing Iterable userId values will be overwritten by incoming Shopify id values.

# Can I use this integration if I have a "headless" or custom Shopify store?

The Iterable + Shopify integration uses Shopify's Ajax Cart API. If your store uses Shopify's Storefront API or a custom cart implementation, purchase events will not include attribution to Iterable campaigns.