Tags: analytics commerce concept

Ecommerce Event Schema

Date: 2026-08-16

---

The one part of your event taxonomy you don’t get to design. Every tool expects the same funnel and the same item array, so the job is conforming precisely rather than choosing well.

---

What it is

The ecommerce event schema is the de facto standard set of event names and property shapes that analytics, advertising and email platforms expect for retail sites.

The funnel, in the order it fires:

view_item_list     a listing or collection page
view_item          a product page
add_to_cart        added
view_cart          basket viewed
begin_checkout     entered checkout
add_shipping_info  delivery step completed
add_payment_info   payment step completed
purchase           order confirmed
refund             order refunded

Google’s spec uses this action-object naming, which conflicts with the object-action convention most taxonomies otherwise adopt. Conform anyway — the whole value is that tools recognise it without mapping. See Event Taxonomy Design on marking inherited events as exempt from your own convention.

The item array

The part that carries the detail, and the part most implementations get subtly wrong:

{
  "event": "add_to_cart",
  "ecommerce": {
    "currency": "GBP",
    "value": 48.00,
    "items": [{
      "item_id": "4471",
      "item_name": "Merino Wool Socks",
      "item_brand": "Example",
      "item_category": "Socks",
      "item_variant": "Charcoal / 8",
      "price": 24.00,
      "quantity": 2
    }]
  }
}

[CHECK: exact field names and which are required have changed between Universal Analytics, GA4 and each vendor’s variant — verify against current documentation before implementing rather than copying this.]

Rules that hold across vendors:

• value is the total for the event, not the unit price. price × quantity, summed across items
• price is per unit, excluding quantity
• currency is mandatory wherever value appears, and must be ISO 4217 — GBP, not £
• item_id must match what your product feed, ad platforms and order system use. A mismatch here quietly breaks every product-level join
• The array is the same shape at every step, so the same item can be traced from list to purchase

Where implementations go wrong

• Decimal versus subunit confusion. The schema wants decimal currency — 24.00 — while Shopify and most commerce APIs store pence. Passing 2400 produces revenue 100× too high, and it’s the single most common ecommerce tracking bug — Revenue Metrics
• value including tax and shipping inconsistently between the site and the order system, so reconciliation never closes
• Discounts applied at basket level but not reflected in item prices, so the item array doesn’t sum to value
• Variant identity. Sending the parent product ID when the variant is what was bought, or vice versa, breaks joins to inventory and ad feeds
• purchase firing on page load of the confirmation page, so a refresh double-counts. Fire on the server’s confirmation, and deduplicate on transaction_id — Double Counting, Idempotency and Deduplication
• Refunds never implemented, so revenue only goes up

Why conform at all

Because the payoff is automatic:

• Ad platforms read it for conversion tracking and dynamic remarketing without a mapping layer
• Email tools read it for abandonment flows — Lifecycle Messaging
• Analytics tools produce funnel and product reports with no configuration
• New vendors integrate faster because they’ve built against the same spec

Deviating means building a translation layer for every tool, forever, and rebuilding it each time one changes.

Where it stops

The schema covers the transactional funnel and nothing else. Everything specific to your business — filter usage, size guides, stock notifications, subscription changes, trade accounts — is yours to design, using your own convention. Conform where the spec exists; design deliberately where it doesn’t, and record which is which in the tracking plan.