Tracking Purchases

This doc 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 will 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 is 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 will have to identify users in order for the approach to work. Even then, this information will not be associated with a client-side session - so you will 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 that 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 is 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




The users email


The ID of the order / transaction


The ID of the product


The name of the product


The category to which the product belongs / was purchased from


The brand associated with the product


The type of product


The ID or name of the product variant


The SKU (Stock Keeping Unit)


The price of the line item


The quantity of the line item purchased


The dollar value of any discount applied to this line item


The discount code applied


The price x quantity


The price x quantity - discount


The currency transacted


The count of this order in the customer's history

Sample Order Event Schema




The user's email


The ID of the order / transaction


The subtotal price of the order before shipping and taxes


The total price of the order including shipping and taxes


The amount charged for shipping


The total amount of discounts applied to the order


The discount code applied to the order


The count of this order in the customer's history