Track purchases

This guide covers how to best utilize our API and data model to track revenue information within Heap. We also have several integrations for capturing revenue information, including Shopify and Stripe. See the Payments section of our Integrations docs for a full list of all integrations offered by Heap.

Behavioral data and marketing data are collected by Heap from your user’s browser. For eCommerce companies, data regarding purchases isn’t readily available for autocapture, so augmenting Heap’s autocapture capabilities with a manual event is necessary. There are two options for you to do this, each with benefits and challenges. Depending on your exact analysis goals, some mixture of these two strategies will be necessary.

Option 1: Sending Purchase Data from the Browser

The first option is to use the client-side track API to record this information. This means that marketing and behavioral data from the session will automatically be associated with the purchase. To facilitate tracking revenue generated by individual users in addition to tracking the conversion rates associated with various products, we recommend setting up two types of custom events. The first is a general purchase event, which records the order size, revenue, and other relevant metadata. The second is fired for every individual line item, with product name, price, and quantity being recorded there. This setup should allow you to achieve many of the most common analysis goals of eCommerce companies. You'll have to have all of the relevant information available on the client’s browser once the order is submitted.

There are challenges that come with sending this data on the client side. The API event has to be configured to only send once per purchase, and not be dropped by a loading page or by a user navigating away early. If the event is fired as the page transitions to the “thank you” page, there's a possibility the call won't be successful. If the call fires on the “thank you” page, then it may be missed if the user navigates away too early. Care needs to be taken to prevent the event from firing again if the user returns to the page at some later point. These challenges, combined with the general challenges of tracking user behavior on the internet (poor connections, ad blockers, etc.), can lead to small discrepancies between the information available in Heap and the information you have stored in your backend.

Option 2: Sending Purchase data from the Server

These inaccuracies can be avoided if a server-side approach is used. The structure of the track calls is very similar to the client-side version - with both a purchase and a line item event being necessary. This approach will guarantee that the information within Heap is completely accurate, but there are some caveats and shortcomings. Server-side events require an identity to properly associate information with data collected from the browser - so you'll have to identify users for the approach to work. Even then, this information will not be associated with a client-side session - so you'll lose insight into associated marketing channel and the ability to use “within a single session” granularities in funnels in the UI.

Mitigating the Shortcomings of the Server-side Approach

If the accuracy of the server-side approach appeals to you, there are ways to enrich your server-side event with information collected on the client side. By parsing the session properties cookie that Heap creates and stores, you can enrich your backend information with this relevant marketing data. Additionally, if you have Heap data sent into a warehouse, you can send the Heap session ID associated with an order and join the information sent from the server with the marketing and behavioral information that's associated with that session. If this is an approach you want to take, please contact [email protected] for details about how we use cookies.

Sample Purchase Event Schema

emailThe users email
order_idThe ID of the order / transaction
product_idThe ID of the product
nameThe name of the product
categoryThe category to which the product belongs / was purchased from
brandThe brand associated with the product
typeThe type of product
variantThe ID or name of the product variant
skuThe SKU (Stock Keeping Unit)
priceThe price of the line item
quantityThe quantity of the line item purchased
discountThe dollar value of any discount applied to this line item
discount_codeThe discount code applied
gross_priceThe price x quantity
net_priceThe price x quantity - discount
currencyThe currency transacted
order_countThe count of this order in the customer's history

Sample Order Event Schema

emailThe user's email
order_idThe ID of the order / transaction
subtotalThe subtotal price of the order before shipping and taxes
totalThe total price of the order including shipping and taxes
shippingThe amount charged for shipping
discountThe total amount of discounts applied to the order
discount_codeThe discount code applied to the order
order_countThe count of this order in the customer's history