Overview

The Heap Shopify source 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.

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.

Event	Property
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 Order	Total 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 Order	Total 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 Item	Gift 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 user’s 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.