caution

You are reading documentation for an outdated version. Here’s the latest one!

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

JavaScript (tag)

Tracker Distribution	Included
sp.js	✅
sp.lite.js	❌

Download:

Download from GitHub Releases (Recommended)	Github Releases (plugins.umd.zip)
Available on jsDelivr	jsDelivr (latest)
Available on unpkg	unpkg (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@3/dist/index.umd.min.js",
  ["snowplowEcommerce", "EcommercePlugin"]
);

Browser (npm)

• npm install @snowplow/browser-plugin-ecommerce
• yarn add @snowplow/browser-plugin-ecommerce
• pnpm add @snowplow/browser-plugin-ecommerce

import { newTracker, trackPageView } from '@snowplow/browser-tracker';
import { EcommercePlugin, addTrans, addItem, trackTrans } from '@snowplow/browser-plugin-ecommerce';

newTracker('sp1', '{{collector_url}}', {
   appId: 'my-app-id',
   plugins: [ 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:

Parameter	Description	Required?	Example value
orderId	Internal unique order id number for this transaction	Yes	'1234'
affiliation	Partner or store affiliation	No	'Womens Apparel'
total	Total amount of the transaction	Yes	'19.99'
tax	Tax amount of the transaction	No	'1.00'
shipping	Shipping charge for the transaction	No	'2.99'
city	City to associate with transaction	No	'San Jose'
state	State or province to associate with transaction	No	'California'
country	Country to associate with transaction	No	'USA'
currency	Currency to associate with this transaction	No	'USD'

For example:

JavaScript (tag)

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'
});

Browser (npm)

This is part of the @snowplow/browser-plugin-ecommerce plugin. You need to install it with your favorite package manager: npm install @snowplow/browser-plugin-ecommerce@3 and then initialize it:

import { newTracker } from '@snowplow/browser-tracker';
import { EcommercePlugin } from '@snowplow/browser-plugin-ecommerce';

newTracker('sp', '{{collector_url_here}}', {
  appId: 'my-app-id',
  plugins: [ EcommercePlugin() ]
});

Used like this for the first step:

import { addTrans } from '@snowplow/browser-plugin-ecommerce'

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:

Parameter	Description	Required?	Example value
orderId	Order ID of the transaction to associate with item	Yes	'1234'
sku	Item's SKU code	Yes	'pbz0001234'
name	Product name	No, but advisable (to make interpreting SKU easier)	'Black Tarot'
category	Product category	No	'Large'
price	Product price	Yes	9.99
quantity	Purchase quantity	Yes	1
currency	Product price currency	No	'USD'

For example:

JavaScript (tag)

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

Browser (npm)

import { addItem } from '@snowplow/browser-plugin-ecommerce'

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:

JavaScript (tag)

snowplow('trackTrans');

Browser (npm)

import { trackTrans } from '@snowplow/browser-plugin-ecommerce';

trackTrans();

Example

JavaScript (tag)

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

Browser (npm)

import { newTracker } from '@snowplow/browser-tracker';
import { EcommercePlugin, addTrans, addItem, trackTrans } from '@snowplow/browser-plugin-ecommerce';

newTracker('sp', '{{collector_url_here}}', {
  appId: 'my-app-id',
  plugins: [ EcommercePlugin() ]
});

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
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.
trackTrans();

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:

Name	Required?	Description	Type
sku	Yes	Item SKU	string
name	No	Item name	string
category	No	Item category	string
unitPrice	Yes	Item price	number
quantity	Yes	Quantity added to or removed from cart	number
currency	No	Item price currency	string

An example:

JavaScript (tag)

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'
});

Browser (npm)

import { trackAddToCart, trackRemoveFromCart } from '@snowplow/browser-plugin-ecommerce';

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

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.