Skip to main content

Ecommerce tracking (original)

tip

This plugin has been superseded by the Snowplow ecommerce plugin. We highly recommend using this newer plugin, which is more fully featured and allows you to use the DBT model we provide.

The original Ecommerce plugin is modeled on Google Analytics ecommerce tracking capability. Snowplow uses three methods that have to be used together to track online transactions:

  1. Create a transaction object. Use addTrans() method to initialize a transaction object. This will be the object that is loaded with all the data relevant to the specific transaction that is being tracked including all the items in the order, the prices of the items, the price of shipping and the order_id.
  2. Add items to the transaction. Use the addItem() method to add data about each individual item to the transaction object.
  3. Submit the transaction to Snowplow using the trackTrans() method, once all the relevant data has been loaded into the object.

Original ecommerce events must be manually tracked.

Install plugin

Tracker DistributionIncluded
sp.js
sp.lite.js

Download:

Download from GitHub Releases (Recommended)Github Releases (plugins.umd.zip)
Available on jsDelivrjsDelivr (latest)
Available on unpkgunpkg (latest)

Note: The links to the CDNs above point to the current latest version. You should pin to a specific version when integrating this plugin on your website if you are using a third party CDN in production.

window.snowplow('addPlugin', 
"https://cdn.jsdelivr.net/npm/@snowplow/browser-plugin-ecommerce@latest/dist/index.umd.min.js",
["snowplowEcommerce", "EcommercePlugin"]
);

Transaction event

Three different event types are included in this plugin: Transaction (trackTrans()), Add-to-cart (trackAddToCart()), and Remove-from-cart (trackRemoveFromCart()).

The transaction object must be created first, using addTrans(). Add items with addItem(), and finally track the event with trackTrans().

addTrans

The addTrans method creates a transaction object. It takes nine possible parameters, two of which are required:

ParameterDescriptionRequired?Example value
orderIdInternal unique order id number for this transactionYes'1234'
affiliationPartner or store affiliationNo'Womens Apparel'
totalTotal amount of the transactionYes'19.99'
taxTax amount of the transactionNo'1.00'
shippingShipping charge for the transactionNo'2.99'
cityCity to associate with transactionNo'San Jose'
stateState or province to associate with transactionNo'California'
countryCountry to associate with transactionNo'USA'
currencyCurrency to associate with this transactionNo'USD'

For example:

snowplow('addTrans', {
orderId: '1234', // required
total: 11.99, // required
affiliation: 'Acme Clothing',
tax: 1.29,
shipping: 5,
city: 'San Jose',
state: 'California',
country: 'USA',
currency: 'USD'
});

addTrans can also be passed an array of custom context entities as an additional parameter. See custom context for more information.

addItem

The addItem method is used to capture the details of each product item included in the transaction. It should therefore be called once for each item.

There are six potential parameters that can be passed with each call, four of which are required:

ParameterDescriptionRequired?Example value
orderIdOrder ID of the transaction to associate with itemYes'1234'
skuItem's SKU codeYes'pbz0001234'
nameProduct nameNo, but advisable (to make interpreting SKU easier)'Black Tarot'
categoryProduct categoryNo'Large'
priceProduct priceYes9.99
quantityPurchase quantityYes1
currencyProduct price currencyNo'USD'

For example:

snowplow('addItem', {
orderId: '1234', // required
sku: 'DD44', // required
name: 'T-Shirt',
category: 'Green Medium',
price: 11.99,
quantity: 1,
currency: 'USD'
});

addItem can also be passed an array of custom context entities as an additional parameter. See custom context for more information.

trackTrans

Once the transaction object has been created (using addTrans) and the relevant item data added to it using the addItem method, we are ready to send the data to the collector. This is initiated using the trackTrans method:

snowplow('trackTrans');

Example

<html>
<head>
<title>Receipt for your clothing purchase from Acme Clothing</title>
<script type="text/javascript">

;(function(p,l,o,w,i,n,g){if(!p[i]){p.GlobalSnowplowNamespace=p.GlobalSnowplowNamespace||[];
p.GlobalSnowplowNamespace.push(i);p[i]=function(){(p[i].q=p[i].q||[]).push(arguments)
};p[i].q=p[i].q||[];n=l.createElement(o);g=l.getElementsByTagName(o)[0];n.async=1;
n.src=w;g.parentNode.insertBefore(n,g)}}(window,document,"script","{{URL to sp.js}}","snowplow"));

snowplow('newTracker', 'sp', '{{collector_url_here}}', { appId: 'my-store' });
snowplow('enableActivityTracking',{
minimumVisitLength: 30,
heartbeatDelay: 10
});
snowplow('trackPageView');
snowplow('enableLinkClickTracking');

snowplow('addTrans', {
orderId: '1234', // required
total: 11.99, // required
affiliation: 'Acme Clothing',
tax: 1.29,
shipping: 5,
city: 'San Jose',
state: 'California',
country: 'USA',
currency: 'USD'
});

// add item might be called for every item in the shopping cart
// where your ecommerce engine loops through each item in the cart and
// prints out _addItem for each
snowplow('addItem', {
orderId: '1234', // required
sku: 'DD44', // required
name: 'T-Shirt',
category: 'Green Medium',
price: 11.99,
quantity: 1,
currency: 'USD'
});

// trackTrans sends the transaction to Snowplow tracking servers.
// Must be called last to commit the transaction.
snowplow('trackTrans'); //submits transaction to the collector

</script>
</head>
<body>

Thank you for your order. You will receive an email containing all your order details.

</body>
</html>

Add to cart & remove from cart events

These methods are also part of @snowplow/browser-plugin-ecommerce and let you track users adding and removing items from a cart on an ecommerce site. Their arguments are identical:

NameRequired?DescriptionType
skuYesItem SKUstring
nameNoItem namestring
categoryNoItem categorystring
unitPriceYesItem pricenumber
quantityYesQuantity added to or removed from cartnumber
currencyNoItem price currencystring

An example:

snowplow('trackAddToCart', {
sku: '000345',
name: 'blue tie',
category: 'clothing',
unitPrice: 3.49,
quantity: 2,
currency: 'GBP'
});

snowplow('trackRemoveFromCart', {
sku: '000345',
name: 'blue tie',
category: 'clothing',
unitPrice: 3.49,
quantity: 2,
currency: 'GBP'
});

Both methods are implemented as Snowplow self describing events. You can see schemas for the add_to_cart and remove_from_cart events.

Was this page helpful?