Shopify + Iterable integration (version 2)

The Shopify app bridges Shopify storefronts and Iterable: when merchants install and configure the integration, Shopify activity can create and update Iterable user profiles, send commerce and custom events, and (when enabled) sync catalog data. Events mirror what merchants do in Shopify—orders, customers, checkouts, fulfillments, and (for traditional storefronts) browser-side behavior captured via Web Pixels.

This article summarizes which Shopify events exist and how they are triggered. Example payloads and Iterable API endpoints per event will be available soon. Ask your Iterable customer success manager for information about example Shopify schema.

# In this article

# Prerequisites

Before installing the app, the merchant should have:

• A Shopify store with permission to install apps.
• An Iterable account.
• A server-side API key for the Iterable project. Shopify uses this key to perform the following actions in Iterable:
  • Add users
  • Update user profile data
  • Track custom events
  • Track commerce events
  • Update Catalog (if using)

# Iterable's European data center (EDC) support

If your Iterable project data is hosted in Iterable's European data center (EDC) location, you must notify your customer success manager (and opt in with your contract) before installing the Shopify app and connecting it to your project. Please note that while you can connect to an EDC-based project, all Shopify data processed by the integration will happen in the US.

# User identity (Shopify customer ID and Iterable user ID)

The integration always sends Shopify’s Customer ID as userId on Iterable API requests, and it includes email when Shopify provides it. That’s fixed behavior: the integration doesn’t let you map a different canonical identifier (for example an internal ID or a non-Shopify userId scheme).

# Install the app from Shopify

1. Open Iterable app listing in the Shopify App Store.
2. Click Install and approve OAuth scopes.
3. Complete setup in the app UI:
   • Iterable Server-side API key
   • Merchant contact email (used once for backfill completion notification)
   • Storefront type (see below)
   • Optional history backfill selections (such as customers, orders)

# Storefront type

Choose the option that best reflects how your storefront is built:

Standard Shopify storefront (themes)

• Built using Shopify’s native theme system
• Supports:
  • Server-side webhooks
  • App-managed Web Pixel events (such as product views, cart updates)

Custom/headless storefront (such as Hydrogen, Next.js)

• Uses a custom frontend outside Shopify themes
• Supports: Server-side webhooks only
• Requires separate instrumentation for browser events (such as Iterable Web SDK). See Headless and Hydrogen support.

# Supported events

Shopify events sent to Iterable are grouped into client-side and server-side events. Availability depends on store type: traditional storefronts support both, while headless or custom implementations support server-side events only. Options in the Shopify app look like this:

For headless or custom storefronts, client-side interactions should be tracked directly using the Iterable Web SDK or similar methods.

# Client-side events

Client-side events are tracked via Shopify Web Pixels and fire only when the appropriate user consent has been granted and the customer has been identified by Shopify (for example, when the user is logged in or previously recognized).

Triggered via Shopify Web Pixel standard events (not webhooks).

# Server-side events

Server-side events are tracked with Shopify webhooks and don't depend on client-side consent or browser state. These events are sent based on changes in Shopify data, such as orders, customers, and fulfillments.

# Customer events

# Order events

In the Iterable Shopify app settings, Orders enables or disables the webhooks in this table together including orders/*, draft_orders/*, and refunds/create (not separate toggles per row).

Orders with no line items are skipped. Gift card–only orders are sent as custom events with eventName: "createGiftCard" instead of purchases.

# Checkout events

Guest checkouts without email or customer ID are skipped. For some stores, checkouts/update sends POST /api/commerce/updateCart instead of a custom track event.

# Fulfillment events

# Catalog integration

When catalog sync is enabled, the app keeps your Iterable catalog aligned with your Shopify products and variants—including initial setup, optional historical backfill, and ongoing automatic updates. Each product creates or updates one product item and one item per variant; deleting a product removes both.

# Backfill (resync)

When enabling catalog sync for the first time, you can optionally provide a "resync from" date:

• Products created on or after this date will be backfilled into Iterable
• If no date is provided, only new and updated products will be synced going forward
• You can run a resync later if you need to reload historical data
• Turning off sync stops future updates, but existing catalog data remains in Iterable

# Iterable catalogs created

The integration creates and maintains two catalogs:

• The product catalog name is based on your Shopify subdomain (such as your-store-shopifyProductCatalog).
• The variant catalog name (shopifyCatalog) is fixed per Iterable project.

# Campaign attribution

Iterable campaign and template IDs can be attached to Shopify cart attributes so they persist through checkout and are included on the resulting order. This allows checkout and purchase events in Iterable to be attributed to the message that drove the session.

There are two ways to send attribution data to Iterable:

1. Enable the Iterable Attribution app embed (recommended): This automatically reads attribution parameters from landing page URLs and stores them on the cart.
2. Custom implementation: Set the supported cart attributes yourself using theme code, the Storefront API, or a headless storefront implementation.

# How it works

1. Campaign and template IDs are stored on the cart as cart attributes.
2. Shopify carries these values into checkout and order note attributes.
3. The integration reads those values and sends them to Iterable as campaignId and templateId on relevant events.

If the attributes are missing or invalid, events are still sent but without attribution.

# URL parameters

Iterable email links (or other landing URLs) should include query parameters that identify the campaign and/or template. The Iterable Attribution app embed automatically reads these parameters and stores them on the Shopify cart.

# Examples

• https://your-store.com/products/example?iterable_campaign=12345&iterable_template=67890
• https://your-store.com/collections/all?utm_campaign=campaign_999

# Enable the Iterable Attribution app embed

For Shopify Online Store 2.0 themes, enable the app embed to automatically apply attribution.

1. In Shopify admin, go to Online Store → Themes.
2. Find the theme that you want to edit, and then click Edit theme.
3. Open App embeds by clicking the icon.
4. Enable Iterable Attribution.
5. Click Save.

See Shopify's documentation for more information.

# Supported attribute names

Use one of the following naming conventions (case-insensitive):

# Where attribution appears

• Checkouts: createCheckout events include campaignId and templateId when present.
• Orders: Purchase events include campaignId and templateId when present.

# Merchant implementation notes

• Theme or app code should set cart attributes as early as possible (for example, when the customer lands from an Iterable email link with UTM or query parameters). Use Liquid, the Storefront API, or your headless client to update the cart with the attribute names above.

• Headless stores must set the same attributes on the cart (or equivalent checkout metadata Shopify maps to note attributes) if you rely on server webhooks for orders and checkouts.

# Headless and Hydrogen support

If your storefront is custom or headless (including Shopify Hydrogen), select Custom / Headless storefront (uses Storefront API) during app setup.

The integration continues to connect Shopify Admin to Iterable in the same way:

• Webhooks power customers, orders, checkouts, and fulfillments.
• Optional catalog sync remains unchanged.

No frontend implementation is required for these server-side flows.

# What is not included out-of-the-box

Headless storefronts do not include built-in client-side tracking:

• Product views
• Cart activity
• Attribution helpers from the theme app extension

Use your own client-side implementation (for example, the Iterable Web SDK) to capture product and cart behavior.

# Example event schemas

Reference the following example schemas for events sent from Shopify to Iterable.

# Client-side event examples

# Product viewed

Track event with eventName: "productView". Fires when a customer visits a product details page. Requires user consent and customer identification. Related Iterable API endpoint: POST /api/events/track

{
  "product_id": "123456789",
  "name": "Product 1",
  "handle": "product-1",
  "description": "Product description",
  "categories": ["Apparel", "T-Shirts"],
  "image_url": "https://cdn.shopify.com/...",
  "url": "https://shop.myshopify.com/products/product-1",
  "vendor": "Vendor Name",
  "product_type": "T-Shirt",
  "tags": ["summer", "sale"],
  "inventory_quantity": 50,
  "price": 29.99,
  "compare_at_price": 39.99
}

# Cart updated

Fires when a customer adds or removes products from their cart. Related Iterable API endpoint: POST /api/commerce/updateCart

{
  "user": {
    "email": "customer@example.com",
    "user_id": "706405506930370084",
    "data_fields": {}
  },
  "items": [
    {
      "id": "42204909568090",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 2,
      "sku": "PROD-1-SKU",
      "url": "https://shop.myshopify.com/products/product-1",
      "image_url": "https://cdn.shopify.com/...",
      "data_fields": {
        "vendor": "Vendor Name",
        "product_id": "123456789",
        "variant_id": "42204909568090",
        "shopify_store_domain": "shop.myshopify.com"
      }
    }
  ]
}

# Customer event examples

The related Iterable API endpoint for all of these examples is POST /api/users/update.

# Customer created

Creates or updates a user profile in Iterable with customer data fields.

{
  "shopify_created_at": "2021-12-31T19:00:00-05:00",
  "shopify_updated_at": "2021-12-31T19:00:00-05:00",
  "first_name": "Bob",
  "last_name": "Biller",
  "note": "VIP customer",
  "tags": "vip, wholesale",
  "currency": "USD",
  "phone_number": "555-555-5555",
  "state": "enabled",
  "verified_email": true,
  "tax_exempt": false,
  "default_address": {
    "address1": "151 O'Connor Street",
    "city": "Ottawa",
    "province": "ON",
    "country": "CA",
    "zip": "K2P 2L8"
  },
  "addresses": []
}

# Customer updated

Same structure as Customer created.

# Customer tags updated

Syncs tags added or removed from a customer profile.

{
  "tags": "tag1, tag2, tag3"
}

# Customer purchasing summary updated

Syncs purchasing summary fields on the user profile.

{
  "orders_count": 1,
  "total_spent": 100.0,
  "last_order_id": "820982911946154508"
}

# Email marketing consent updated

Syncs email marketing consent status.

{
  "email_marketing_consent": {
    "state": "subscribed",
    "opt_in_level": "single_opt_in",
    "consent_updated_at": "2025-05-05T04:00:00.000Z"
  }
}

# SMS marketing consent updated

Syncs SMS marketing consent status.

{
  "sms_marketing_consent": {
    "state": "not_subscribed",
    "opt_in_level": null,
    "consent_updated_at": null
  }
}

# Customer disabled

Triggered when a customer profile is disabled in Shopify. Data fields include state: "disabled".

{
  "state": "disabled"
}

# Customer enabled

Triggered when a customer profile is enabled in Shopify. Data fields include state: "enabled".

{
  "state": "enabled"
}

# Order event examples

The related Iterable API endpoint for all of these examples is POST /api/events/track, except where explicitly stated.

# Order created

Purchase event sent when a new order is created. Orders with no line items are skipped. Gift card–only orders are sent as createGiftCard events instead (via POST /api/events/track. Related Iterable API endpoint: POST /api/commerce/trackPurchase

{
  "id": "820982911946154508",
  "email": "customer@example.com",
  "name": "#1001",
  "order_number": "1001",
  "currency": "USD",
  "update": false,
  "tags": ["vip", "wholesale"],
  "totals": {
    "total_price": 369.97,
    "total_tax": 0.0,
    "total_discounts": 20.0,
    "subtotal_price": 359.97
  },
  "items": [
    {
      "id": "866550311766439020",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 1,
      "sku": "PROD-1-SKU",
      "product_id": "123456789",
      "variant_id": "808950810"
    }
  ],
  "billing_address": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "shipping_address": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "fulfillment_status": null,
  "misc": { "financial_status": "paid", "confirmed": true }
}

# Order updated

Uses the same trackPurchase request as Order created. The boolean update helps distinguish between order creation and later changes. Initial order creation events are sent with update: false, while subsequent updates (for example, fulfillment, refunds, edits, or address changes) are sent with update: true. This makes it easier to build logic in Iterable based on order lifecycle. Related Iterable API endpoint: POST /api/commerce/trackPurchase

Below is the same order as in Order created, after the line item has been fulfilled: order-level fulfillment_status and line-item fulfillment fields change; totals and addresses are unchanged.

{
  "id": "820982911946154508",
  "email": "customer@example.com",
  "name": "#1001",
  "order_number": "1001",
  "currency": "USD",
  "update": true,
  "tags": ["vip", "wholesale"],
  "totals": {
    "total_price": 369.97,
    "total_tax": 0.0,
    "total_discounts": 20.0,
    "subtotal_price": 359.97
  },
  "items": [
    {
      "id": "866550311766439020",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 1,
      "sku": "PROD-1-SKU",
      "product_id": "123456789",
      "variant_id": "808950810",
      "fulfillment_status": "fulfilled"
    }
  ],
  "billing_address": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "shipping_address": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "fulfillment_status": "fulfilled",
  "misc": { "financial_status": "paid", "confirmed": true }
}

Other real-world updates use the same shape with different deltas. For example financial_status moving to partially_refunded after a return, tags changing, or totals reflecting adjustments.

# Order cancelled

Track event with eventName: "cancelOrder".

{
  "id": "820982911946154509",
  "email": "customer@example.com",
  "cancelled_at": "2026-10-10T19:00:00-05:00",
  "cancel_reason": "customer"
}

# Draft order created

Shopify sends the draft_orders/create webhook. Track event with eventName: "createDraftOrder".

{
  "total": 150.0,
  "shopify_created_at": "2025-01-15 15:00:00 -05:00",
  "shopify_updated_at": "2025-01-15 15:00:02 -05:00",
  "email": "customer@example.com",
  "taxes_included": false,
  "currency": "USD",
  "totals": {
    "subtotal_price": 130.0,
    "total_tax": 20.0,
    "total_price": 150.0
  },
  "invoice_sent_at": "2025-01-15 16:00:00 -05:00",
  "completed_at": null,
  "name": "Draft #D123",
  "status": "open",
  "billing_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "123 Main St",
    "city": "New York",
    "province": "NY",
    "country": "United States",
    "zip": "10001"
  },
  "shipping_address": {
    "first_name": "John",
    "last_name": "Doe",
    "address1": "456 Oak Ave",
    "city": "Brooklyn",
    "province": "NY",
    "country": "United States",
    "zip": "11201"
  },
  "invoice_url": "https://shop.myshopify.com/invoices/abc123",
  "order_id": null,
  "tax_lines": [{ "title": "State Tax", "rate": 0.08 }],
  "note_attributes": { "custom_field": "custom_value" },
  "tags": ["vip", "custom"],
  "items": [
    {
      "id": "111111",
      "product_id": "222222",
      "variant_id": "333333",
      "name": "Custom Widget",
      "sku": "WIDGET-001",
      "vendor": "Acme Corp",
      "quantity": 2,
      "price": 50.0,
      "grams": 500,
      "gift_card": false,
      "fulfillment_service": "manual",
      "fulfillment_status": null,
      "requires_shipping": true,
      "taxable": true,
      "total_discount": "10.00",
      "description": "Product description",
      "categories": ["Apparel"],
      "image_url": "https://cdn.shopify.com/...",
      "url": "https://shop.myshopify.com/products/widget"
    }
  ],
  "shipping_line": {
    "title": "Standard Shipping",
    "price": "10.00",
    "code": "STANDARD"
  },
  "customer": {
    "id": "987654321",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+1234567890"
  },
  "update": false
}

# Draft order updated

Shopify sends the draft_orders/update webhook. Track event with eventName: "createDraftOrder" (same as Draft order created). The dataFields shape matches the example above.

# Refund created

Shopify sends the refunds/create webhook. Track event with eventName: "createRefund". Payloads are built from the refund webhook plus enrichment from Shopify (refund line items and customer context).

{
  "order_id": "450789469",
  "created_at": "2026-10-10 15:00:00 -05:00",
  "note": "Customer requested return",
  "user_id": "987654321",
  "processed_at": "2026-10-10 15:05:00 -05:00",
  "restock": true,
  "items": [
    {
      "sku": "PROD-1-SKU",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 1,
      "description": "Product description",
      "categories": ["Apparel"],
      "image_url": "https://cdn.shopify.com/...",
      "url": "https://shop.myshopify.com/products/product-1",
      "data_fields": {
        "product_id": "123456789",
        "variant_id": "808950810",
        "line_item_id": "866550311766439020",
        "restock_type": "return",
        "subtotal": 199.0,
        "total_tax": 0.0
      }
    }
  ],
  "transactions": [
    {
      "id": "123456789",
      "order_id": "450789469",
      "kind": "refund",
      "amount": 199.0,
      "status": "success",
      "gateway": "shopify_payments",
      "currency": "USD"
    }
  ],
  "order_adjustments": []
}

# Checkout event examples

# Checkout created

Track event with eventName: "createCheckout". Guest checkouts without email or customer ID are skipped. Related Iterable API endpoint: POST /api/events/track

{
  "id": "981824079252243534",
  "token": "test-token-123",
  "email": "customer@example.com",
  "currency": "USD",
  "update": false,
  "totals": {
    "total_price": 447.99,
    "total_tax": 0.0,
    "subtotal_price": 447.99
  },
  "line_items": [
    {
      "sku": "PROD-1-SKU",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 2
    }
  ],
  "shipping_address": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "abandoned_checkout_url": "https://shop.myshopify.com/checkouts/token/recover"
}

# Checkout updated

Same structure as Checkout created, with "update": true in dataFields when the checkout was modified after creation. Related Iterable API endpoint: POST /api/events/track (or POST /api/commerce/updateCart for some stores).

{
  "id": "981824079252243534",
  "email": "customer@example.com",
  "update": true,
  "totals": { "total_price": 447.99 },
  "line_items": [
    {
      "name": "Product 1",
      "price": 199.0,
      "quantity": 2
    }
  ]
}

# Fulfillment event examples

The related Iterable API endpoint for all of these examples is POST /api/events/track.

# Fulfillment created

Track event with eventName: "createFulfillment".

{
  "id": "255858046",
  "orderId": "450789469",
  "status": "success",
  "created_at": "2026-10-10T20:00:00-05:00",
  "tracking_company": "FedEx",
  "tracking_number": "123456789",
  "tracking_url": "https://tracking.fedex.com/123456789",
  "shipment_status": "in_transit",
  "destination": { "city": "Ottawa", "country": "CA", "zip": "K2P 2L8" },
  "items": [
    {
      "id": "866550311766439020",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 1,
      "sku": "PROD-1-SKU"
    }
  ]
}

# Fulfillment updated

Same structure as Fulfillment created.

# Fulfillment tracking

Track event with status-based event names: orderDelivered, orderInTransit, orderCarrierPickedUp, orderOutForDelivery, orderLabelPrinted, orderLabelPurchased, orderAttemptedDelivery, orderShippingConfirmed, orderDelayed, orderDeliveryFailure, orderReadyForPickup.

{
  "id": "12345678",
  "fulfillment_id": "255858046",
  "order_id": "450789469",
  "status": "delivered",
  "happened_at": "2026-10-12T14:00:00-05:00",
  "tracking_number": "123456789",
  "tracking_url": "https://tracking.fedex.com/123456789",
  "city": "Ottawa",
  "province": "ON",
  "country": "CA",
  "zip": "K2P 2L8",
  "items": [
    {
      "id": "866550311766439020",
      "name": "Product 1",
      "price": 199.0,
      "quantity": 1
    }
  ]
}

# Catalog schema examples

The Shopify integration creates and maintains two catalogs in Iterable:

# Product Catalog

• Name: {store-subdomain}-shopifyProductCatalog
• Item ID: Shopify product ID

{
  "id": "123456789",
  "name": "Summer T-Shirt",
  "description": "Lightweight tee",
  "product_type": "Shirts",
  "category": "Apparel",
  "vendor": "Acme",
  "tags": "summer,sale",
  "handle": "summer-t-shirt",
  "url": "https://your-store.myshopify.com/products/summer-t-shirt",
  "image_url": "https://cdn.shopify.com/...",
  "additional_images": "https://cdn.shopify.com/a.jpg,https://cdn.shopify.com/b.jpg",
  "starting_price": 29.99,
  "max_price": 34.99,
  "compare_at_price_min": 39.99,
  "compare_at_price_max": 39.99,
  "on_sale": true,
  "options": [{ "id": "987", "name": "Size", "values": ["S", "M", "L"] }],
  "total_inventory": 120,
  "created_at": "2021-01-15 10:00:00 -05:00",
  "updated_at": "2024-03-01 14:30:00 -05:00",
  "published_at": "2021-01-15 10:00:00 -05:00",
  "published": true,
  "status": "ACTIVE"
}

# Variant Catalog

• Name: shopifyCatalog
• Item ID: Shopify variant ID

{
  "id": "42204909568090",
  "product_id": "123456789",
  "sku": "TEE-S-BLK",
  "name": "Summer T-Shirt",
  "variant_name": "Black / S",
  "handle": "summer-t-shirt",
  "description": "Lightweight tee",
  "categories": "summer,sale",
  "price": 29.99,
  "inventory": 10,
  "imageUrl": "https://cdn.shopify.com/...",
  "url": "https://your-store.myshopify.com/products/summer-t-shirt",
  "vendor": "Acme",
  "product_type": "Shirts",
  "compare_at_price": 39.99,
  "discount": 10.0,
  "tags": "summer,sale",
  "inventory_quantity": 10,
  "inventory_policy": "deny",
  "published": true,
  "status": "ACTIVE",
  "sales_channels_and_apps": "shopify"
}

# Want to learn more?

For step-by-step and implementation-focused guidance (including Hydrogen-oriented notes), refer to Shopify–Iterable custom integration.