Skip to main content

Snowplow Ecommerce

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

This plugin is the recommended way to track ecommerce events on your store. Functions, usage and a complete setup journey is showcased on the E-commerce Web Accelerator.

Installation

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

The plugin is available since version 3.8 of the tracker.

Initialization

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

newTracker('sp1', '{{collector_url}}', {
appId: 'my-app-id',
plugins: [ SnowplowEcommercePlugin() ],
});

Functions

APIUsed for:
trackProductViewTracking a visit to a product page. Known also as product detail view.
trackAddToCartTrack an addition to cart.
trackRemoveFromCartTrack a removal from cart.
trackProductListViewTrack an impression of a product list. The list could be a search results page, recommended products, upsells etc.
trackProductListClickTrack the click/selection of a product from a product list.
trackPromotionViewTrack an impression for an internal promotion banner or slider or any other type of content that showcases internal products/categories.
trackPromotionClickTrack the click/selection of an internal promotion.
trackCheckoutStepTrack a checkout step completion in the checkout process together with common step attributes for user choices throughout the checkout funnel.
trackTransactionTrack a transaction/purchase completion.
trackRefundTrack a transaction partial or complete refund.
trackTransactionErrorTrack an error happening during a transaction process.
setPageTypeSet a Page type context which would allow the analyst to discern between types of pages with ecommerce value. E.g. Category Page, Product Page, Cart Page, etc.
setEcommerceUserSet a User type context with a few standard user attributes.

Usage

trackProductView

To track a product view you can use the trackProductView method with the following attributes:

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

trackProductView({
id: "12345",
name: "Baseball T",
brand: "Snowplow",
category: "apparel",
price: 200,
currency: "USD",
});

trackAddToCart

To track a product/s addition to the cart you can use the trackAddToCart method with the following attributes:

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

trackAddToCart({
products: [
{
id: "P125",
name: "Baseball T",
brand: "Snowplow",
category: "Mens/Apparel",
price: 200,
currency: "USD",
},
],
total_value: 200,
currency: "USD",
});
  • Where products is an array with the product/s added to cart.
  • Where total_value is the value of the cart after the addition.
  • Where currency is the currency of the cart.

trackRemoveFromCart

To track a product/s removal from the cart you can use the trackRemoveFromCart method with the following attributes:

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

trackRemoveFromCart({
products: [
{
id: "P125",
name: "Baseball T",
brand: "Snowplow",
category: "Mens/Apparel",
price: 200,
currency: "USD",
},
],
total_value: 0,
currency: "USD",
});
  • Where products is an array with the product/s removed from the cart.
  • Where total_value is the value of the cart after the removal of the product/s.
  • Where currency is the currency of the cart.

trackProductListView

To track a product list view you can use the trackProductListView method with the following attributes:

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

trackProductListView({
products: [
{
id: "P123",
name: "Fashion red",
brand: "Snowplow",
category: "Mens/Apparel",
price: 100,
inventory_status: "in stock",
currency: "USD",
position: 1,
},
{
id: "P124",
name: "Fashion green",
brand: "Snowplow",
category: "Mens/Apparel",
price: 119,
inventory_status: "in stock",
currency: "USD",
position: 2,
},
{
id: "P125",
name: "Baseball T",
brand: "Snowplow",
category: "Mens/Apparel",
price: 200,
inventory_status: "in stock",
currency: "USD",
position: 3,
},
],
name: "Recommended Products",
});
  • Where products is an array of products being viewed from the list.
  • Where name is the name of the list being viewed. For the list names, you can use any kind of friendly name or a codified language to express the labeling of the list. E.g. 'Shoes - Men - Sneakers','Search results: "unisex shoes"', 'Product page upsells'

trackProductListClick

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

trackProductListClick({
product: {
id: "P124",
name: "Fashion green",
brand: "Snowplow",
category: "Mens/Apparel",
price: 119,
inventory_status: "in stock",
currency: "USD",
position: 2,
},
name: "Recommended Products",
});
  • Where product is the product being clicked/selected from the list.
  • Where name is the name of the list the product is currently in. For the list names, you can use any kind of friendly name or a codified language to express the labeling of the list. E.g. 'Shoes - Men - Sneakers','Search results: "unisex shoes"', 'Product page upsells'

trackPromotionView

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

/* Carousel slide 1 viewed */
trackPromotionView({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
position: 1,
product_ids: ['P1234'],
});

/* On carousel slide 2 view */
trackPromotionView({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
position: 2,
product_ids: ['P1235'],
});

trackPromotionClick

import { trackPromotionClick } from "@snowplow/browser-plugin-snowplow-ecommerce";

trackPromotionClick({
id: 'IP1234',
name: 'promo_winter',
type: 'carousel',
position: 1,
product_ids: ['P1234'],
});

trackCheckoutStep

To track a checkout step you can use the trackCheckoutStep method with the following attributes:

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

/* Step 1 - Account type selection */
trackCheckoutStep({
step: 1,
account_type: "guest checkout",
});

/* Step 2 - Billing options selection */
trackCheckoutStep({
step: 2,
payment_method: "credit card",
proof_of_payment: "invoice",
});

trackTransaction

To track a completed transaction you can use the trackTransaction method with the following attributes:

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

trackTransaction({
transaction_id: "T12345",
revenue: 230,
currency: "USD",
payment_method: "credit_card",
total_quantity: 1,
tax: 20,
shipping: 10,
products: [
{
id: "P125",
name: "Baseball T",
brand: "Snowplow",
category: "Mens/Apparel",
price: 200,
inventory_status: "in stock",
currency: "USD",
},
],
});
  • Where products is an array with the product/s taking part in the transaction.

trackRefund

note

Available from version 3.10.

To track a complete or partial refund you can use the trackRefund method with the following attributes:

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

trackRefund({
transaction_id: "T12345",
currency: "USD",
refund_amount: 200,
refund_reason: "return",
products: [
{
id: "P125",
name: "Baseball T",
brand: "Snowplow",
category: "Mens/Apparel",
price: 200,
inventory_status: "in stock",
currency: "USD",
},
],
});
  • Where products is an array with the product/s taking part in the refund.

trackTransactionError

note

Available from version 3.13.

To track an error happening during a transaction process you can use the trackTransactionError method with the following attributes:

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

trackTransactionError({
resolution: "rejection",
error_code: "E123",
error_shortcode: "CARD_DECLINE",
error_description: "Card has been declined by the issuing bank.",
error_type: "hard",
transaction: {
revenue: 45,
currency: "EUR",
transaction_id: "T12345",
payment_method: "card",
total_quantity: 1
}
});
  • Where transaction is the transaction entity being processed.

setPageType

To set a Page type context you can use the setPageType method with the following attributes:

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

setPageType({ type, language, locale });

After setting the Page context, it will be attached to every subsequent Snowplow event.

setEcommerceUser

To set an Ecommerce User context you can use the setEcommerceUser method with the following attributes:

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

setEcommerceUser({ id, is_guest, email });

After setting the Page context, it will be attached to every subsequent Snowplow event.

Entities

Below is the set of entities and attributes that can be used in the Snowplow Ecommerce implementation.

Ecommerce page entity

An ecommerce page entity can have the following attributes:

attributetypedescriptionrequired
typestringThe type of the page that was visited E.g. homepage, product page, checkout page.
languagestringThe language that the web page is based in.
localestringThe locale version of the site that is running.
Relevant Iglu schema

Ecommerce user entity

An ecommerce user entity can have the following attributes:

attributetypedescriptionrequired
idstringThe user ID.
is_guestbooleanWhether or not the user is a guest.
emailstringThe user's email address.
Relevant Iglu schema

Product entity

Whenever there is a product entity involved in the ecommerce interaction event, the product or array of products can have the following attributes:

attributetypedescriptionrequired
idstringSKU or product ID.
currencystringCurrency in which the product is being priced (ISO 4217).
pricenumberPrice of the product at the current time.
namestringName or title of the product.
categorystringCategory the product belongs to. Use a consistent separator to express multiple levels. E.g. Woman/Shoes/Sneakers. The number of levels is defined by the user.
list_pricenumberRecommended or list price of a product.
quantitynumberQuantity of the product taking part in the action. Used for Cart events.
sizestringSize of the product. E.g. XL, XS, M.
variantstringVariant of the product. E.g. Red, Heavy, Leather.
brandstringBrand of the product.
inventory_statusstringInventory status of the product. E.g. in stock, out of stock, preorder, backorder.
positionnumberPosition the product was presented in a list of products. Used in Product List events.
creative_idstringIdentifier/Name/Url for the creative presented on a list or product view.
Relevant Iglu schema

Internal promotion entity

On internal promotion events, an internal promotion can have the following attributes:

attributetypedescriptionrequired
idstringThe unique ID representing this promotion element.
namestringThe friendly name for this promotion element.
product_idsstring[]An array of SKUs or product IDs showcased in this promotion element.
positionintegerThe position this promotion element was presented in a list of promotions E.g. banner, slider.
creative_idstringIdentifier/Name/Url for the creative presented on this promotion element.
typestringThe type of the promotion delivery mechanism. E.g. popup, banner, intra-content.
slotstringThe website slot in which the promotional content was added to. E.g. Identifier for slot sidebar-1, intra-content-2.
Relevant Iglu schema

Cart entity

On cart interaction ecommerce events, a cart can have the following attributes:

attributetypedescriptionrequired
total_valuenumberThe total value of the cart after this interaction.
currencystringThe currency used for this cart (ISO 4217).
cart_idstringThe unique ID representing this cart.
Relevant Iglu schema

Checkout step entity

Whenever there is a checkout entity involved in the ecommerce interaction event, it can have the following attributes:

attributetypedescriptionrequired
stepnumberCheckout step index.
shipping_postcodestringShipping address postcode.
billing_postcodestringBilling address postcode.
shipping_full_addressstringFull shipping address.
billing_full_addressstringFull billing address.
delivery_providerstringCan be used to discern delivery providers DHL, PostNL etc.
delivery_methodstringCan be used to discern delivery methods selected E.g. store pickup, standard delivery, express delivery, international.
coupon_codestringCoupon applied at checkout.
account_typestringType of account used on checkout. E.g. existing user, guest.
payment_methodstringAny kind of payment method the user selected to proceed E.g. card, PayPal, Alipay etc.
proof_of_paymentstringInvoice or receipt.
marketing_opt_inbooleanIf opted in to marketing campaigns.
Relevant Iglu schema

Transaction entity

Whenever there is a transaction entity involved in the ecommerce interaction event, it can have the following attributes:

attributetypedescriptionrequired
transaction_idstringThe ID of the transaction
currencystringThe currency used for the transaction (ISO 4217).
revenuenumberThe revenue of the transaction.
payment_methodstringThe payment method used for the transaction.
total_quantitynumberTotal quantity of items in the transaction.
taxnumberTotal amount of tax on the transaction.
shippingnumberTotal cost of shipping on the transaction.
discount_codestringDiscount code used.
discount_amountnumberDiscount amount taken off.
credit_orderbooleanWhether the transaction is a credit order or not.
Relevant Iglu schema

Refund entity

Whenever there is a refund entity involved in the ecommerce interaction event, it can have the following attributes:

attributetypedescriptionrequired
transaction_idstringThe ID of the transaction
currencystringThe currency used for the transaction (ISO 4217).
refund_amountnumberThe amount refunded from the transaction.
refund_reasonstringThe reason that resulted in a refund.
Relevant Iglu schema

Transaction Error entity

Whenever there is a transaction error entity involved in the ecommerce interaction event, it can have the following attributes:

attributetypedescriptionrequired
error_codestringError-identifying code for the transaction issue. E.g. E522
error_shortcodestringShortcode for the error occurred in the transaction. E.g. declined_by_stock_api, declined_by_payment_method, card_declined, pm_card_radarBlock
error_descriptionnumberLonger description for the error occurred in the transaction.
error_typeEnum stringEither 'hard' or 'soft'. Hard error types mean the customer must provide another form of payment e.g. an expired card. Soft errors can be the result of temporary issues where retrying might be successful e.g. processor declined the transaction.
resolutionstringThe resolution selected for the error scenario. E.g. retry_allowed, user_blacklisted, block_gateway, contact_user, default
Relevant Iglu schema

GA4/UA Ecommerce transitional API

note

Available from version 3.10.

If you already use Google Analytics 4 ecommerce or Universal Analytics Enhanced Ecommerce to collect information about the shopping behavior of your users, we have prepared a way to quickly implement Snowplow Ecommerce without making many changes on your current setup.

The transitional API that we provide, depends on the standardized dataLayer structure for both Google Analytics ecommerce implementations. This would make it easier for the transition to happen either through Google Tag Manager, which has more control over the dataLayer, or custom code that uses the standard ecommerce structures.

info

To learn more about how to use this transitional API, you should go ahead and visit our Ecommerce Web Accelerator dedicated page which describes the usage of these methods and more.

Universal Analytics Enhanced Ecommerce

The standard Universal Analytics Enhanced Ecommerce implementation is based on the official guide reference.

Important: The dataLayer.currencyCode attribute must be available for all product interactions. Otherwise, almost all methods accept an Options object which can include the currency code as follows:

method({{dataLayer.ecommerce reference}} , { currency: "currency code" });

trackEnhancedEcommerceProductListView

To track an Enhanced Ecommerce product list view, you can use the trackEnhancedEcommerceProductListView method with the following attributes:

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

trackEnhancedEcommerceProductListView({{dataLayer.ecommerce reference}});

trackEnhancedEcommerceProductListClick

To track an Enhanced Ecommerce product list click, you can use the trackEnhancedEcommerceProductListClick method with the following attributes:

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

trackEnhancedEcommerceProductListClick({{dataLayer.ecommerce reference}});

trackEnhancedEcommerceProductDetail

To track an Enhanced Ecommerce product detail view, you can use the trackEnhancedEcommerceProductDetail method with the following attributes:

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

trackEnhancedEcommerceProductDetail({{dataLayer.ecommerce reference}});

trackEnhancedEcommercePromoView

To track an Enhanced Ecommerce internal promotion view, you can use the trackEnhancedEcommercePromoView method with the following attributes:

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

trackEnhancedEcommercePromoView({{dataLayer.ecommerce reference}});

trackEnhancedEcommercePromoClick

To track an Enhanced Ecommerce internal promotion click, you can use the trackEnhancedEcommercePromoClick method with the following attributes:

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

trackEnhancedEcommercePromoClick({{dataLayer.ecommerce reference}});

trackEnhancedEcommerceAddToCart

To track an Enhanced Ecommerce add to cart event, you can use the trackEnhancedEcommerceAddToCart method with the following attributes:

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

trackEnhancedEcommerceAddToCart( {{dataLayer.ecommerce reference}}, {
finalCartValue: 20,
});
  • Where finalCartValue is the value of the cart after the addition.

trackEnhancedEcommerceRemoveFromCart

To track an Enhanced Ecommerce remove from cart event, you can use the trackEnhancedEcommerceRemoveFromCart method with the following attributes:

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

trackEnhancedEcommerceRemoveFromCart( {{dataLayer.ecommerce reference}}, {
finalCartValue: 20,
});
  • Where finalCartValue is the value of the cart after the removal.

trackEnhancedEcommerceCheckoutStep

To track an Enhanced Ecommerce remove from cart event, you can use the trackEnhancedEcommerceCheckoutStep method with the following attributes:

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

trackEnhancedEcommerceCheckoutStep( {{dataLayer.ecommerce reference}}, {
checkoutOption: { delivery_method: "express_delivery" },
});
  • Where checkoutOption is a key value pair object of available Snowplow checkout options, except step which is retrieved from the dataLayer directly.

trackEnhancedEcommercePurchase

To track an Enhanced Ecommerce remove from cart event, you can use the trackEnhancedEcommercePurchase method with the following attributes:

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

trackEnhancedEcommercePurchase( {{dataLayer.ecommerce reference}}, {
paymentMethod: "bank_transfer",
});
  • Where paymentMethod is the payment method selected in this transaction. This attributes corresponds to the payment_method of the transaction schema. Defaults to unknown.

Google Analytics 4 Ecommerce

The Google Analytics 4 ecommerce implementation is based on the official guide reference.

Important: The dataLayer.ecommerce.currency attribute must be available for all product interactions. Otherwise, almost all methods accept an Options object which can include the currency code as follows:

method( {{dataLayer.ecommerce reference}} , { currency: "currency code" });

trackGA4ViewItemList

To track an GA4 Ecommerce item list view, you can use the trackGA4ViewItemList method with the following attributes:

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

trackGA4ViewItemList({{dataLayer.ecommerce reference}});

trackGA4SelectItem

To track an GA4 Ecommerce item selection from a list, you can use the trackGA4SelectItem method with the following attributes:

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

trackGA4SelectItem({{dataLayer.ecommerce reference}});

trackGA4ViewItem

To track an GA4 Ecommerce item view, you can use the trackGA4ViewItem method with the following attributes:

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

trackGA4ViewItem({{dataLayer.ecommerce reference}});

trackGA4ViewPromotion

To track an GA4 Ecommerce internal promotion view, you can use the trackGA4ViewPromotion method with the following attributes:

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

trackGA4ViewPromotion({{dataLayer.ecommerce reference}});

trackGA4SelectPromotion

To track an GA4 Ecommerce internal promotion selection, you can use the trackGA4SelectPromotion method with the following attributes:

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

trackGA4SelectPromotion( {{dataLayer.ecommerce reference}});

trackGA4AddToCart

To track an GA4 Ecommerce add to cart event, you can use the trackGA4AddToCart method with the following attributes:

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

trackGA4AddToCart( {{dataLayer.ecommerce reference}}, {
finalCartValue: 20,
});
  • Where finalCartValue is the value of the cart after the addition.

trackGA4RemoveFromCart

To track an GA4 Ecommerce remove from cart event, you can use the trackGA4RemoveFromCart method with the following attributes:

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

trackGA4RemoveFromCart( {{dataLayer.ecommerce reference}}, {
finalCartValue: 20,
});
  • Where finalCartValue is the value of the cart after the removal.

trackGA4BeginCheckout

To track an GA4 Ecommerce checkout beginning, you can use the trackGA4BeginCheckout method with the following attributes:

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

trackGA4BeginCheckout({
step: 1,
});
  • Where step is a number representing the step of the checkout funnel. Defaults to 1, mimicking the begin_checkout GA4 event.

trackGA4AddShippingInfo

To track an GA4 Ecommerce checkout shipping info step completion, you can use the trackGA4AddShippingInfo method with the following attributes:

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

trackGA4AddShippingInfo({
step: 1,
});
  • Where step is a number representing the step of the checkout funnel.

trackGA4AddPaymentOptions

To track an GA4 Ecommerce checkout payment option step completion, you can use the trackGA4AddPaymentOptions method with the following attributes:

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

trackGA4AddPaymentOptions({
step: 1,
});
  • Where step is a number representing the step of the checkout funnel.

trackGA4Transaction

To track an GA4 Ecommerce checkout payment option step completion, you can use the trackGA4Transaction method with the following attributes:

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

trackGA4Transaction({
paymentMethod: "bank_transfer",
});
  • Where paymentMethod is the payment method selected in this transaction. This attributes corresponds to the payment_method of the transaction schema. Defaults to unknown.