Shopify + Iterable Integration

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.

# In this article

# 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

1. Install the Iterable app from the Shopify App Store (available here).

2. Read and accept the required permissions of the app.

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

   

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

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

   

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

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

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

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

# 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 a fulfillment_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

# 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 documentation about the Customer Object.

# Product tracking

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:

# 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 and iterableTemplateId 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 feature

• 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

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.

# Will the Shopify integration populate the userId user profile field?

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