Skip to main content

Ecommerce tracking


Snowplow ecommerce tracking was added in version 5.4.0. With the addition of these new ecommerce events and entities, we have deprecated the old EcommerceTransaction and EcommerceTransactionItem events. Migration guide.

The Snowplow ecommerce tracking APIs enable you to track events from your ecommerce store on the web as well as mobile apps. A complete setup journey, including data modeling and visualization, is showcased in the Ecommerce Accelerator.

All ecommerce events must be manually tracked; there is no ecommerce auto-tracking.

Ecommerce events​

Ecommerce events are tracked like normal Snowplow events. For example, tracking an ecommerce ProductViewEvent event:

let tracker = Snowplow.createTracker(namespace: "appTracker", endpoint: "")

let product = ProductEntity(
id: "productId",
category: "category",
currency: "GBP",
price: 100
let event = ProductViewEvent(product: product)
let eventId = tracker.track(event)

Add or update properties using setters. For example, adding data to a PromotionEntity:

let promotion = PromotionEntity(id: "promoId") = "bogof"
promotion.type = "popup"

This table lists all the ecommerce events.

EventUsed for
ProductViewEventTracking a visit to a product detail screen. Also known as product detail view.
AddToCartEventTrack an addition to cart.
RemoveFromCartEventTrack a removal from cart.
ProductListViewEventTrack an impression of a product list. The list could be a search results page, recommended products, upsells etc.
ProductListClickEventTrack the click/selection of a product from a product list.
PromotionViewEventTrack an impression for an internal promotion banner or slider or any other type of content that showcases internal products/categories.
PromotionClickEventTrack the click/selection of an internal promotion.
CheckoutStepEventTrack a checkout step completion in the checkout process together with common step attributes for user choices throughout the checkout funnel.
TransactionEventTrack a transaction/purchase completion.
TransactionErrorEventTrack a failed transaction.
RefundEventTrack a transaction partial or complete refund.

Each ecommerce event is a self-describing event using a single schema, iglu:com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2.

Ecommerce action event properties
Request KeyRequiredType/FormatDescription
typeYstringSpecific ecommerce event type (automatically tracked).
nameNstringFor ProductListView and ProductListClick events: human-readable list name

The events are distinguished by their type property, which is different for each Event class tracked. Aside from the optional list name in the ProductListViewEvent and ProductListClickEvent events, all tracked ecommerce properties are tracked as entities.


Check out the API docs (Android, iOS) for the full details of each Event and Entity.


Tracking a visit to a details screen for a specific product.

let product = ProductEntity(
id: "plow2",
category: "snow.clearance.ploughs.large",
currency: "NOK",
price: 5000
let event = ProductViewEvent(product: product)



Tracking one or more products being added to a cart.

let product = ProductEntity(
id: "productId",
category: "clothes/shirts",
currency: "EUR",
price: 100.50
let cart = CartEntity(totalValue: 200, currency: "EUR")
let event = AddToCartEvent(products: [product], cart: cart)



Tracking one or more products being removed from a cart.

let product = ProductEntity(id: "productId", category: "clothes/shirts", currency: "EUR", price: 100.50)
let cart = CartEntity(totalValue: 200, currency: "EUR")
let event = RemoveFromCartEvent(products: [product], cart: cart)



Track an impression of a list of products. You can optionally provide a name for the list.

let product = ProductEntity(id: "productId", category: "software", currency: "USD", price: 99.99)
let event = ProductListViewEvent(products: [product], name: "snowplowProducts")



Track a specific product being selected from a list. You can optionally provide a name for the list.

let product = ProductEntity(id: "productId", category: "software", currency: "USD", price: 99.99)
let event = ProductListClickEvent(product: product, name: "snowplowProducts")



Track the completion of a step in the checkout funnel, along with common checkout properties such as payment method or coupon code. See the API docs for the full details (Android, iOS).

let event = CheckoutStepEvent(step: 3, deliveryMethod: "next_day")



Track the completion of a purchase or transaction, along with common transaction properties such as shipping cost or discount amount.

let transaction = TransactionEntity(
transactionId: "id-123",
revenue: 50000,
currency: "JPY",
paymentMethod: "debit",
totalQuantity: 2
let event = TransactionEvent(transaction)



Track an error occurring during a transaction.

let transaction = TransactionEntity(
transactionId: "id-123",
revenue: 50000,
currency: "JPY",
paymentMethod: "debit",
totalQuantity: 2
let event = TransactionErrorEvent(
transaction: transaction,
errorCode: "E05",
errorDescription: "connection_failure"



Track a refund being requested for part of, or the entirety of, a transaction.

let event = RefundEvent(
transactionId: "id-123", // use the transaction ID from the original Transaction event
refundAmount: 20000,
currency: "JPY"



Track an impression for any kind of internal promotion.

let promotion = PromotionEntity(id: "promoId")
let event = PromotionViewEvent(promotion: promotion)



Track an internal promotion being selected.

let promotion = PromotionEntity(id: "promoId")
let event = PromotionViewEvent(promotion: promotion)


Ecommerce entities​

Product entity​

The product entity is used in several ecommerce events. It contains information about the product the user is interacting with.

Product entity properties
Request KeyRequiredType/FormatDescription
idYstringThe SKU or product ID.
categoryYstringCategory the product belongs to.
currencyYstringCurrency in which the product is priced.
priceYnumberCurrent price.
listPriceNbooleanRecommended or list price.
nameNstringProduct name or title.
quantityNintegerQuantity of the product (for cart events).
sizeNstringProduct size.
variantNstringProduct variant.
brandNstringProduct brand.
inventoryStatusNstringInventory status, e.g. in stock.
positionNintegerPosition in a list of products.
creativeIdNstringIdentifier for the creative shown.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/product/jsonschema/1-0-0.

Cart entity​

The cart entity is used for AddToCart and RemoveFromCart events.

Cart entity properties
Request KeyRequiredType/FormatDescription
totalValueYnumberTotal cart value after this action.
currencyYstringCurrency used for the cart.
cartIdNstringUnique cart identifier.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/cart/jsonschema/1-0-0.

Checkout step entity​

The checkout step entity is used for CheckoutStep events.

Checkout step entity properties
Request KeyRequiredType/FormatDescription
stepYintegerCheckout step index.
shippingPostcodeNstringShipping address postcode.
billingPostcodeNstringBilling address postcode.
shippingFullAddressNstringShipping address.
billingFullAddressNstringBilling address.
deliveryProviderNstringDelivery provider e.g. DHL, Royal Mail.
deliveryMethodNstringHow the customer will get the product.
couponCodeNstringAn applied coupon.
accountTypeNstringCustomer account type, e.g. guest
paymentMethodNstringPayment method selected.
proofOfPaymentNstringe.g. invoice, receipt
marketingOptInNbooleanWhether the user email address is opted into marketing campaigns.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/checkout_step/jsonschema/1-0-0.

Transaction entity​

The transaction entity is used for Transaction and TransactionError events.

Transaction entity properties
Request KeyRequiredType/FormatDescription
transactionIdYstringUnique transaction identifier.
revenueYnumberValue of transaction.
currencyYstringCurrency used in transaction.
paymentMethodYstringPayment method used.
totalQuantityYintegerNumber of items in the transaction.
taxNnumberTax value in transaction.
shippingNnumberShipping costs in transaction.
discountCodeNstringAn applied discount code.
discountAmountNstringAmount discounted from transaction.
creditOrderNbooleanWhether the transaction is a credit order.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/transaction/jsonschema/1-0-0.

Transaction error entity​

The transaction error entity is used for TransactionError events.

Transaction error entity properties
Request KeyRequiredType/FormatDescription
errorCodeNstringError-identifying code.
errorShortcodeNstringShortcode for the error.
errorDescriptionNstringLonger description.
errorTypeNstring enumIs the error "hard" or "soft".
resolutionNstringThe chosen error resolution.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/transaction_error/jsonschema/1-0-0.

Refund entity​

The refund entity is used for Refund events.

Refund entity properties
Request KeyRequiredType/FormatDescription
transactionIdYstringThe identifier from the original transaction.
refundAmountYnumberAmount to be refunded.
currencyYstringCurrency used in transaction.
refundReasonNstringReason for the refund.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/refund/jsonschema/1-0-0.

Promotion entity​

The promotion entity is used for PromotionView and PromotionClick events.

Promotion entity properties
Request KeyRequiredType/FormatDescription
idYstringThe unique promotion identifier.
nameNstringPromotion name.
productIdsNlist of stringsIDs of products in the promotion.
positionNintegerIndex of the promotion in a list such as a banner.
creativeIdNstringIdentifier for the promotion creative.
typeNstringType of promotion.
slotNstringWhere the promotion was displayed.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/promotion/jsonschema/1-0-0.

Global ecommerce entities Screen/Page and User​

Use these APIs to add ecommerce context information to every subsequent event tracked.


These entities will be added to all events, not just ecommerce ones. This is for consistency with entities in the JavaScript tracker.

Ecommerce Screen (Page) entity​


The setEcommerceScreen method adds a Page (rather than Screen) entity to all events, for consistency with web tracking.

The Ecommerce Screen/Page entity helps in grouping insights by screen/page type, e.g. Product description, Product list, Home screen.

To set a Screen/Page entity you can use the setEcommerceScreen method:

let entity = EcommerceScreenEntity(type: "demo_app_screen")

// setting EcommerceScreen again will replace the original entity
let newEntity = EcommerceScreenEntity(type: "product_list", language: "EN-GB", locale: "UK")

// remove the saved properties and stop the Page entity being added
Screen/Page entity properties
Request KeyRequiredType/FormatDescription
typeYstringType of screen.
languageNstringLanguage used for the screen.
localeNstringLocale version.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/page/jsonschema/1-0-0.

Ecommerce User entity​

The Ecommerce User entity helps in modeling guest/non-guest account interactions.

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

let entity = EcommerceUserEntity(id: "userId12345", isGuest: true)

// setting EcommerceUser again will replace the original entity
let newEntity = EcommerceUserEntity(id: "userId67890", isGuest: false, email: "")

// remove the saved properties and stop the User entity being added
User entity properties
Request KeyRequiredType/FormatDescription
idYstringThe unique user identifier.
isGuestNbooleanWhether the user is a guest.
emailNstringUser email address.

Schema: iglu:com.snowplowanalytics.snowplow.ecommerce/user/jsonschema/1-0-0.

Was this page helpful?