Skip to content
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
  • Home
  • Developers
  • API
  • Releases
  • Community
  • University
  • Status
Home Integrations Commerce Platform Shopify Integration
Session Replay Getting Started Administration Data Management Definitions Charts Analysis Examples Heap Plays Integrations Heap Connect Data Privacy

Table of Contents

Was this article helpful?

Yes No

Thank you for your feedback!

Shopify Integration

In this article you'll learn:

  • How to format events and properties being sent between Heap and Shopify
This doc is for: Admins Architects

This guide is for customers that already have Heap installed on their Shopify store.

To install Heap on your Shopify store for the first time, visit Shopify Installation Guide .

Overview

The Heap Shopify integration automatically captures all Shopify order events, as well as any user properties available in Shopify including order aggregations (like LTV) or customer information (like their name and preferences) via the Shopify API.

With the Heap Shopify source, you can:

  • Segment your users by customer lifetime value and purchasing behavior
  • Understand what customer behavior and demographics are correlated with repeat purchases
  • Determine purchase conversion rates by product and identify bottlenecks for low performing products

To connect the Shopify source, you’ll need the following:

  • Admin or Architect permissions in Heap
  • Store Owner access to your Shopify account
  • The name of your Shopify shop(s) (ex. companyname.myshopify.com)

While not required to use the Shopify Source, if you want to also track client-side events, you need to install Heap on your Shopify site. See our Shopify installation instructions to set this up.

Multiple Shopify Storefronts

You can have multiple Shopify storefronts connected to the same Heap environment. After you have set up one storefront, contact us via the Get support page to add additional storefronts.

Setup

This setup is unnecessary for some installs

If you installed Heap by authorizing Shopify during the Heap installation process, this integration was automatically connected for you. You do not need to connect this integration again.

If you are looking to install Heap on a domain hosted by Shopify, see our Shopify install instructions.

Email Join Key Required

You need to have email addresses attached to your users in Heap to match data between Heap and this source. This property can be set to identity or any custom user property in Heap.

If you are not currently sending email addresses into Heap you will need to use Heap’s APIs to do so. Learn more about attaching email data to users via Heap’s identity API.

If you need help, please post in Heap Community or visit our Get support page.

To get started, visit the Shopify source in the app and click Set Up in the top right corner of the page.

You will then be prompted to specify an email property if you haven’t set one up already for your account. The selected user property needs to be the user property associated with your users’ email addresses as this is the property Shopify uses when sending Heap data about your users.

You will next be redirected to install the Heap app in your Shopify store and authenticate the integration. Once authenticated, you’ll be redirected back to the Shopify source page in Heap with a successful confirmation message.

Upon completion, the source connection page will say Waiting For Data until the first event data from Shopify is seen by Heap, at which point the connection status will change to Connected.

If you need help, please post in Heap Community or visit our Get support page.

Note: Shopify has a separate theme for the checkout page that is only available to their higher-tiered customers. If you do not have access to this theme to add the Heap installation snippet, then you will not be able to track events on this page. To learn more, see Shopify’s documentation on Upgrading your online checkout.

Data Format

Events

Shopify source events have the following event types in Heap:

  • Confirmed Order: When an order was paid for.
  • Confirmed Line Item: When a line item, product, or SKU was paid for.
  • Cancelled Order: When an order was cancelled.
  • Cancelled Line Item: When a line item, product, or SKU was cancelled.
  • Fulfilled Order: When an item in the order was shipped.
  • Placed Order: When an order was placed.
  • Refunded Order: When a refund on at least part of the order occurred.
  • Refunded Line Item: When a line item, product, or SKU was refunded.

Event Schema

The events will have the following event properties when provided by Shopify.

EventProperty
Confirmed OrderOrder ID
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Name
Referring Site
Landing Site
Landing Site UTM Source
Landing Site UTM Medium
Landing SIte UTM Term
Landing Site UTM Content
Landing Site UTM Campaign
Total Price USD
Source Name
Customer Locale
Browser IP
Processing Method
Tags
Billing Address First Name
Billing Address Last Name
Billing Address State/Province
Billing Address Name
Discount Codes
Line Items
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Net Revenue
Shop URL
Checkout Token
Placed OrderRefund ID
Order ID
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Name
Referring Site
Landing Site
Landing Site UTM Source
Landing Site UTM Medium
Landing SIte UTM Term
Landing Site UTM Content
Landing Site UTM Campaign
Total Price USD
Source Name
Customer Locale
Browser IP
Processing Method
Tags
Billing Address First Name
Billing Address Last Name
Billing Address State/Province
Billing Address Name
Discount Codes
Line Items
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Net Revenue
Shop URL
Checkout Token
Cancelled OrderOrder ID
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Name
Referring Site
Landing Site
Landing Site UTM Source
Landing Site UTM Medium
Landing SIte UTM Term
Landing Site UTM Content
Landing Site UTM Campaign
Cancel Reason
Total Price USD
Source Name
Customer Locale
Browser IP
Processing Method
Tags
Billing Address First Name
Billing Address Last Name
Billing Address State/Province
Billing Address Name
Discount Codes
Line Items
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Net Revenue
Shop URL
Checkout Token
Fulfilled OrderFulfillment ID
Order ID
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Name
Referring Site
Total Price USD
Source Name
Customer Locale
Browser IP
Order Number
Processing Method
Tags
Billing Address First Name
Billing Address Last Name
Billing Address State/Province
Billing Address Name
Discount Codes
Refunds
Line Items
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Tracking Company
Tracking Number
Fulfillment Status
Shop URL
Checkout Token
Refunded OrderRefund ID
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Name
Referring Site
Total Price USD
Source Name
Customer Locale
Browser IP
Order Number
Processing Method
Tags
Billing Address First Name
Billing Address Last Name
Billing Address State/Province
Billing Address Name
Discount Codes
Refunds
Refund Line Items
Refund Transactions
Net Revenue
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Shop URL
Checkout Token
Confirmed Line Item
Cancelled Line Item
Product ID
SKU
Variant ID
Vendor
Gift Card
Line Item ID
Price
Quantity
Requires Shipping
Shop URL
Taxable
Title
Total Discount
Variant Title
Refunded Line ItemOrder ID
Refund ID
Gift Card
Line Item ID
Product ID
Quantity
Refund Line Item ID
Requires Shipping
Restock Type
Shop URL
SKU
Price
Subtotal
Taxable
Title
Line item Name
Total Discount
Total Tax
Variant ID
Variant Title
Vendor
Refund Line Item Quantity
Refund Line Item Restock Type
Refund Line Item Subtotal
Refund Line Item Tax

Event Properties

  • Billing Address First Name: The customer’s first name.
  • Billing Address Last Name: The customer’s last name.
  • Billing Address Name: The full name of the person associated with the payment method.
  • Billing Address State/Province: The name of the state or province of the billing address.
  • Browser IP: The IP address of the browser used by the customer when placing the order.
  • Buyer Accepts Marketing: Indicates whether the customer has consented to be sent marketing material via email. Valid values are “true” or “false”.
  • Cancel Reason: The reason why the order was cancelled. If the order was not cancelled, this value is “null”. If the order was cancelled, the value will be “customer”, “fraud”, “inventory”, “declined”, or “other”.
  • Currency: The three letter code (ISO 4217) for the currency used for the payment.
  • Customer Locale: The two or three letter language code, optionally followed by a region
  • modifier. Example values could be ‘en’, ‘en-CA’, ‘en-PIRATE’.
  • Discount Codes: Applicable discount codes that can be applied to the order.
  • Fulfillment ID: The unique numeric identifier for the fulfillment. Only available on fulfillment events.
  • Fulfillment Status: The status of the fulfillment.
  • Landing Site: The URL for the page where the customer landed when entering the shop.
  • Landing Site UTM Campaign: The UTM campaign of the page where the customer landed when entering the shop.
  • Landing Site UTM Content: The UTM content of the page where the customer landed when entering the shop.
  • Landing Site UTM Medium: The UTM medium of the page where the customer landed when entering the shop.
  • Landing Site UTM Source: The UTM source of the page where the customer landed when entering the shop.
  • Landing Site UTM Term: The UTM term of the page where the customer landed when entering the shop.
  • Line Item Product IDs: A list of product IDs of line items in the order.
  • Line Item SKUs: A list of product SKUs of line items in the order.
  • Line Item Titles: A list of titles of line items in the order.
  • Line Items: A list of line item objects, each one containing information about an item in
  • the order.
  • Name: The customer’s order name as represented by a number.
  • Net Revenue: The event’s contribution towards sales revenue. Refunds will have a negative value. We recommend using this for any revenue analysis.
  • Order ID: The unique numeric identifier for the order.
  • Order Number: A unique numeric identifier for the order. This one is used by the shop owner and customer. This is different from the id property, which is also a unique numeric identifier for the order, but used for API purposes.
  • Processing Method: The type of payment processing method. Valid values are: checkout, direct, manual, offsite or express.
  • Referring Site: The website that the customer clicked on to come to the shop.
  • Refund ID: The unique numeric identifier for the refund. Only available on refund events.
  • Refund Line Items: A list of line item objects that were refunded, each one
  • containing information about an item in the order.
  • Refund Transactions: The list of transactions involved in the refund.
  • Source Name: Where the order originated. Orders created through official Shopify channels will have protected values of “web”, “pos”, “iphone”, or “android”. Orders created via the API may have values of “api” or any other non-protected string.
  • Subtotal Price: The price of the order before shipping and taxes.
  • Tags: Additional short descriptors, commonly used for filtering and searching,
  • formatted as a string of comma-separated values.
  • Taxes Included: Whether or not taxes are included in the order subtotal. Valid values are
  • “true” or “false”.
  • Total Discounts: The total amount of the discounts to be applied to the price of the order.
  • Total Line Items Price: The sum of all the prices of all the items in the order.
  • Total Price: The sum of all the prices of all the items in the order, taxes and discounts included (must be positive).
  • Total Price USD: The sum of all the prices of all the items in the order, taxes and discounts
  • included, converted to USD (must be positive).
  • Total Tax: The sum of all the taxes applied to the order (must be positive).
  • Total Weight: The sum of all the weights of the line items in the order, in grams.
  • Tracking Company: The name of the shipping company.
  • Tracking Number: The shipping number, provided by the shipping company.

User Properties

Heap will also automatically capture a variety of user properties from Shopify that are automatically stored on your users based on email address:

  • Accepts Marketing: Indicates whether the customer has consented to be sent marketing material via email. Valid values are “true” or “false”.
  • Account Status: The status of the customer’s account in a shop. Valid status are “disabled”, “invited”, “enabled”, and “declined”.
  • Billing Address State/Province: The name of the state or province of the billing address.
  • Customer ID: A unique numeric identifier for the customer.
  • Customer Order Count: The number of orders associated with this customer all time.
  • Customer Total Spent: The total amount of money that the customer has spent at the shop all time.
  • First Name: The customer’s first name.
  • Last Name: The customer’s last name.
  • Note: Extra information about the customer.
  • Tags: Additional short descriptors formatted as a string of comma-separated values.

Was this article helpful?

Yes No

Thank you for your feedback!

Last updated December 6, 2022.

integrationshopifyshopify source
  • Blog
  • Partners
  • Legal
  • Security
  • Terms
  • About
  • Careers
  • Privacy
  • Contact Us

© 2023 Heap, Inc.