Skip to main content

E-commerce events

Snowplow provides support for tracking and modeling events from e-commerce stores directly in our trackers and data models.

Events and context entities​

E-commerce action event​

Each ecommerce event is a self-describing event using a single e-commerce action schema.

The events are distinguished by their type property, which is different for each Event class tracked.

Event: snowplow_ecommerce_action

Schema for an Ecommerce action

Schema URI: iglu://com.snowplowanalytics.snowplow.ecommerce/snowplow_ecommerce_action/jsonschema/1-0-2

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "type": "list_view",
  "name": "shop the look"
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
typeOne of: add_to_cart, remove_from_cart, product_view, list_click, list_view, promo_click, promo_view, checkout_step, transaction, refund, trns_errorStandard ecommerce actions.✅
name["string","null"]The name of the list presented to the user E.g. product list, search results, shop the look, frequently bought with.❌
❓ How to query the event in the warehouse?
select
  unstruct_event_com_snowplowanalytics_snowplow_ecommerce_snowplow_ecommerce_action_1_0_2
from
  PIPELINE_NAME.events events
where
  events.collector_tstamp > timestamp_sub(current_timestamp(), interval 1 hour)
  and events.event = 'unstruct'
  and events.event_name = 'snowplow_ecommerce_action'
  and events.event_vendor = 'com.snowplowanalytics.snowplow.ecommerce'

E-commerce context entities​

All tracked e-commerce properties are tracked as context entities.

Cart​

Context entity: cart

Schema for a cart entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "cart_id": null,
  "currency": "EUR",
  "total_value": 12
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
cart_id["string","null"]The unique ID representing this cart.❌
total_value"number"The total value of the cart after this interaction.✅
currency"string"The currency used for this cart (ISO 4217).✅

Checkout step​

Context entity: checkout_step

Schema for a checkout step entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "step": 2,
  "account_type": "guest",
  "billing_full_address": null,
  "billing_postcode": null,
  "coupon_code": null,
  "delivery_method": null,
  "delivery_provider": null,
  "marketing_opt_in": null,
  "payment_method": null,
  "proof_of_payment": null,
  "shipping_full_address": null,
  "shipping_postcode": null
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
step"integer"Checkout step index.✅
shipping_postcode["string","null"]Shipping address postcode.❌
billing_postcode["string","null"]Billing address postcode.❌
shipping_full_address["string","null"]Full shipping address.❌
billing_full_address["string","null"]Full billing address.❌
delivery_provider["string","null"]Can be used to discern delivery providers DHL, PostNL etc.❌
delivery_method["string","null"]Can be used to discern delivery methods selected E.g. store pickup, standard delivery, express delivery, international.❌
coupon_code["string","null"]Coupon applied at checkout.❌
account_type["string","null"]Type of account used on checkout. E.g. existing user, guest.❌
payment_method["string","null"]Any kind of payment method the user selected to proceed E.g. card, PayPal, Alipay etc.❌
proof_of_payment["string","null"]Invoice or receipt.❌
marketing_opt_in["boolean","null"]If opted in to marketing campaigns.❌

Page​

Context entity: page

Schema for a page entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "type": "checkout step 1",
  "language": null,
  "locale": null
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
type"string"The type of the page that was visited E.g. homepage, product page, checkout page.✅
language["string","null"]The language that the web page is based in.❌
locale["string","null"]The locale version of the site that is running.❌

Product​

Context entity: product

Schema for a product entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "id": "1236",
  "name": null,
  "category": "Hats",
  "price": 12,
  "list_price": null,
  "quantity": null,
  "size": null,
  "variant": null,
  "brand": "Snowplow",
  "inventory_status": null,
  "position": null,
  "currency": "EUR",
  "creative_id": null
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
id"string"The SKU or product ID.✅
name["string","null"]The name or title of the product.❌
category"string"The category the product belongs to. Use a consistent separator to express multiple levels. E.g. Woman/Shoes/Sneakers✅
price"number"The price of the product at the current time.✅
list_price["number","null"]The list or recommended retail price of a product.❌
quantity["integer","null"]The quantity of the product taking part in the ecommerce action.❌
size["string","null"]The size of the product.❌
variant["string","null"]The variant of the product.❌
brand["string","null"]The brand of the product.❌
inventory_status["string","null"]The inventory status of the product E.g. in stock, out of stock, preorder, backorder.❌
position["integer","null"]The position the product was presented in a list of products E.g. search results, product list page.❌
currency"string"The currency in which the product is being priced (ISO 4217).✅
creative_id["string","null"]Identifier/Name/Url for the creative presented on a list or product view.❌

Promotion​

Context entity: promotion

Schema for a promotion entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
id"string"The ID of the promotion.✅
name["string","null"]The name of the promotion.❌
product_ids["array","null"]Array of SKUs or product IDs showcased in the promotion.❌
position["integer","null"]The position the promotion was presented in a list of promotions E.g. banner, slider.❌
creative_id["string","null"]Identifier/Name/Url for the creative presented on the promotion.❌
type["string","null"]Type of the promotion delivery mechanism. E.g. popup, banner, intra-content❌
slot["string","null"]The website slot in which the promotional content was added to. E.g. Identifier for slot sidebar-1, intra-content-2❌

Refund​

Context entity: refund

Schema for a refund in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
transaction_id"string"The ID of the transaction.✅
currency"string"The currency in which the product is being priced (ISO 4217).✅
refund_amount"number"The monetary amount refunded.✅
refund_reason["string","null"]Reason for refunding the whole or part of the transaction.❌

Transaction​

Context entity: transaction

Schema for a transaction entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "transaction_id": "TtlZ3b",
  "currency": "EUR",
  "payment_method": "BNPL",
  "revenue": 13,
  "total_quantity": 1,
  "credit_order": null,
  "discount_amount": null,
  "discount_code": null,
  "shipping": 1,
  "tax": null
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
transaction_id"string"The ID of the transaction.✅
revenue"number"The revenue of the transaction.✅
currency"string"The currency used for the transaction (ISO 4217).✅
payment_method"string"The payment method used for the transaction.✅
total_quantity"integer"Total quantity of items in the transaction.✅
tax["number","null"]Total amount of tax on the transaction.❌
shipping["number","null"]Total cost of shipping on the transaction.❌
discount_code["string","null"]Discount code used.❌
discount_amount["number","null"]Discount amount taken off.❌
credit_order["boolean","null"]Whether the transaction is a credit order or not.❌

Transaction error​

Context entity: transaction_error

Schema for a transaction error or rejection entity in ecommerce.

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

WebMobileTracked automatically
✅✅❌
👀 Example
{}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
error_code["string","null"]Error-identifying code for the transaction issue. E.g. E522❌
error_shortcode["string","null"]Shortcode for the error occurred in the transaction. E.g. declined_by_stock_api, declined_by_payment_method, card_declined, pm_card_radarBlock❌
error_description["string","null"]Longer description for the error occurred in the transaction.❌
error_typeOne of: hard, 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.❌
resolution["string","null"]The resolution selected for the error scenario. E.g. retry_allowed, user_blacklisted, block_gateway, contact_user, default❌

User​

Context entity: user

Schema for an user entity in Ecommerce

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

WebMobileTracked automatically
✅✅❌
👀 Example
{
  "id": "U12345",
  "email": "john@email.com",
  "is_guest": true
}
📃 Schema properties definition
PropertyTypeDescriptionRequired?
id"string"The user ID.✅
is_guest["boolean","null"]Whether or not the user is a guest.❌
email["string","null"]The user's email address.❌

How to track?​

Modeled data using the snowplow-ecommerce dbt package​

The package contains a fully incremental model that transforms raw e-commerce event data into a set of derived tables based around the following e-commerce data objects: carts, checkouts, products and transactions.

Derived tableTable description
snowplow_ecommerce_base_events_this_runBase: Performs the incremental logic, the table contains a de-duped data set of all events required for the current run of the model, and is the foundation for all other models generated.Docs
snowplow_ecommerce_cart_interactionsCarts: Parses the cart interactions that occur to provide handy filters and aggregations, which helps identify what happened to carts on a session level to extract, for example, abandoned carts with ease.Docs
snowplow_ecommerce_checkout_interactionsCheckouts: Parses checkout steps that occur to provide handy filters and aggregations to help identify which checkout steps were walked through, and what details were entered in each of these steps. This lends itself well to a funnel analysis.Docs
snowplow_ecommerce_product_interactionsProducts: Parses product view and list information to provide insights into which products were being viewed, what details were being shown to the end user and how the user then interacted with these products.Docs
snowplow_ecommerce_transaction_interactionsTransactions: Parses transaction actions to provide insights into which transactions occurred, how much revenue was generated from them, and other insights leveraging the many properties of the transaction e-commerce context.Docs
snowplow_ecommerce_sessionsSessions: Aggregates all other data into a sessions table which leverages the domain_sessionid.Docs

E-commerce analytics accelerator​

Follow the e-commerce accelerator for a complete guide to build a deeper understanding of customer behavior in your ecommerce store.

Old e-commerce events

Some of our trackers also provide ecommerce tracking APIs for older ecommerce events. This is no longer the recommended approach to track ecommerce events.

Transaction tracking​

Transaction events allow you to track a transaction. The items of the transaction can be tracked using Transaction Item events.

ParameterTable ColumnTypeDescription
tr_idtr_orderidtextOrder ID
tr_aftr_affiliationtextTransaction affiliation (e.g. channel)
tr_tttr_totaldecimalTransaction total value
tr_txtr_taxdecimalTransaction tax value (i.e. amount of VAT included)
tr_shtr_shippingdecimalDelivery cost charged
tr_citr_citytextDelivery address: city
tr_sttr_statetextDelivery address: state
tr_cotr_countrytextDelivery address: country
tr_cutr_currencytextTransaction Currency

Transaction item events​

Transaction item events are separate events, representing the items of a transaction, which are linked to a Transaction event via ti_id which should map to tr_id of a transaction event.

ParameterTable ColumnTypeDescriptionExample values
ti_idti_orderidtextOrder ID12345
ti_skti_skutextItem SKUYes
ti_nmti_nametextItem nameYes
ti_cati_categorytextItem categoryYes
ti_prti_pricedecimalItem priceYes
ti_quti_quantityintegerItem quantityYes
ti_cuti_currencytextCurrencyYes
Was this page helpful?