Skip to content
  • Home
  • University
  • Developers
  • API
  • Releases
  • Status
  • Home
  • University
  • Developers
  • API
  • Releases
  • Status
Home Integrations Most Popular Shopify Integration
Getting Started Installation Administration Define & Analyze Analysis Examples Heap Plays Success Guides 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:

  • Steps to send data between Heap and Shopify via Shopify's API
  • How to format events and properties being sent between Heap and Shopify
This doc is for: Admins Architects
View instructions for: 

Overview

This integration is only available for customers on a paid plan. To upgrade, contact sales@heap.io.

The Heap Shopify integration automatically captures all Shopify server-side transactional events (order completion, order fulfillment, etc.) 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.

Setup

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

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

  1. Admin or Architect privileges in Heap
  2. Admin access to your Shopify account
  3. The name of your Shopify shop(s) (generally companyname.myshopify.com)

To get started, visit the Shopify integration in the app and click Contact Us, or contact your Heap Account Manager directly expressing interest. We’ll follow up to enable your trial of Shopify and confirm your Shopify shop names with you. You’ll also need to specify an email property for your users if you haven’t already set one up for your selected environment.

Email User Property Required

The property selected for Shopify needs to map to an email address user property (or identity) in Heap and this property cannot be changed once selected. Please don’t hesitate to support@heap.io if you’re unsure of what you want to select, or if you have the required data in Heap for this source.

Upon enabling your environment for Shopify access, you’ll need to follow a custom link for each Shopify store that will authenticate Heap’s access to your Shopify data. Once complete, we’ll begin to backfill Shopify data from a date of your preference.

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 Order
Cancelled Order
Placed Order
Total Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
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 State/Province
Discount Codes
Line Items
Line Item Product IDs
Line Item SKUs
Line Item Titles
Line Item Names
Net Revenue
Shop URL
Checkout Token
Cancel Reason
Refunds
Fulfilled OrderTotal Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Referring Site
Total Price USD
Source Name
Customer Locale
Browser IP
Processing Method
Tags
Billing Address State/Province
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 OrderTotal Price
Subtotal Price
Total Weight
Total Tax
Taxes Included
Currency
Total Discounts
Total Line Items Price
Buyer Accepts Marketing
Referring Site
Total Price USD
Source Name
Customer Locale
Browser IP
Processing Method
Tags
Billing Address State/Province
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
Note
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 ItemGift Card
Line Item ID
Product ID
Quantity
Refund Line Item ID
Requires Shipping
Restock Type
Shop URL
SKU
Subtotal
Taxable
Title
Total Discount
Total Tax
Variant ID
Variant Title
Vendor

All 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 February 1, 2021.

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

© 2021 Heap, Inc.