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)
• A user property that can be used as a join key between Heap and Shopify (see the section below)

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.

Join key requirements

This integration requires:

1. A user property to be used as a join key between Heap and Shopify
2. At least one user with the join key user property must already exist in Heap before you set up this integration. For example, if you want to use an email address as your join key, a user with an email address associated with it must already exist in Heap

What is a join key?

A join key is a user property that Heap uses to reconcile users across sources. If you have an existing user in Heap, and a user from Shopify with the same value for your join key property, Heap will associate the events from Shopify with their existing Heap sessions.

How do I bring user properties into Heap?

User properties are brought into Heap via the addUserProperties API or the identify API.

Default join key

If you have previously set up a join key at the environment level, Heap will default to using it in your Shopify integration. If you want to use another join key, please contact us via the Get support page in Heap.

Using email address as a join key

Outside the Shopify integration, to bring email addresses into Heap you’ll need to use Heap’s APIs. Learn more about attaching email data to users via Heap’s identity API.

For example, a basic Shopify installation may have email addresses formatted within the customer or checkout object as customer.email or checkout.email. This will vary depending on your Shopify implementation.

What if a user exists in Shopify, but not Heap?

If a user exists in Shopify but not Heap, we’ll create a user. This user will only have Shopify events and properties associated with them, unless you send data from another source into Heap and we can match the identities.

Need help? Please post in Community or contact us via the Get support page in Heap.

Event enrichment

Beginning in May 2024, we have made a series of updates to improve the ability to do session-level analysis when using Shopify transaction events. 

Shopify events are added server-side by contacting Shopify’s API (versus individual clicks, pageviews, etc. that are captured client-side on each end-user’s device). When using these server-side Shopify events in Heap, we’ll now automatically apply values of session-level properties from the most recent client-side session (as long as the session started less than two hours earlier than the Shopify event). 

This will make it much easier to accurately aggregate metrics like conversions, revenue, and more by session properties like Landing Page or Marketing Channel. 

These properties include:

• Session ID 
• Platform
• Device Type
• Country
• Region
• City
• IP
• Referrer
• Landing Page
• Landing Page Query
• Landing Page Hash
• Browser
• Search Keyword
• UTM Source
• UTM Campaign
• UTM Medium
• UTM Term
• UTM Content
• Device
• Carrier
• App Name
• App Version
• Heap Device ID 
• Heap app Name
• Heap app Version
• Heap Device 

Note that these values are applied at read time, so they’ll both work retroactively and have no impact on any previously or newly stored event data.

Because this enrichment happens at read time, there’s no impact on the data sent to Heap Connect. Customers must implement custom sessionization in a data warehouse via Heap Connect if they want to mirror this enrichment of Shopify events downstream. To learn more, see the Sessionizing Client-Side and Server-Side Events section of the Heap Connect Common Queries guide. 

Setup

1. Go to Shopify source in the app and click Set Up in the top right corner of the page.
2. Select your preferred join key from the drop-down. If you already have a default join key set, you’ll skip this step and be directed to Shopify to complete the setup.
3. You’ll be redirected to install the Heap app in your Shopify store and authenticate the integration. 
4. Once authenticated, you’ll be redirected back to the Shopify source page in Heap with a successful confirmation message.

Upon completion, the Shopify connection page will say Waiting For Data. Once Heap has data from Shopify, the connection status will change to Connected. This process should take less than one hour. 

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.

Event	Property
Confirmed Order	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
Placed Order	Refund 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 Order	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 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 Order	Fulfillment 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 Order	Refund 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 Item	Order 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.