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 Warehouses, 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

Key

Description

email

The users email

order_id

The ID of the order / transaction

product_id

The ID of the product

name

The name of the product

category

The category to which the product belongs / was purchased from

brand

The brand associated with the product

type

The type of product

variant

The ID or name of the product variant

sku

The SKU (Stock Keeping Unit)

price

The price of the line item

quantity

The quantity of the line item purchased

discount

The dollar value of any discount applied to this line item

discount_code

The discount code applied

gross_price

The price x quantity

net_price

The price x quantity - discount

currency

The currency transacted

order_count

The count of this order in the customer's history

Sample Order Event Schema

Key

Description

email

The user's email

order_id

The ID of the order / transaction

subtotal

The subtotal price of the order before shipping and taxes

total

The total price of the order including shipping and taxes

shipping

The amount charged for shipping

discount

The total amount of discounts applied to the order

discount_code

The discount code applied to the order

order_count

The count of this order in the customer's history

Updated 4 months ago

Tracking Purchases


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.