Designing a GA4 Ecommerce DataLayer Schema That Survives Contact with Reality

Most dataLayer schemas look clean in the spec doc and fall apart the moment a second developer touches the checkout flow. The fix isn't more documentation — it's fewer places where the shape can drift.

The four events that carry 90% of ecommerce reporting

1. view_item_list — a list of items rendered on screen
2. add_to_cart — one explicit user action, one item (or a clean array)
3. begin_checkout — the cart snapshot at the moment checkout starts
4. purchase — the same snapshot, plus a transaction id and totals

Keep items[] shape identical across all four

If add_to_cart uses item_id and begin_checkout uses sku, every downstream funnel report has to reconcile two keys for the same concept. Pick one item schema and reuse it everywhere:

interface DataLayerItem {
  item_id: string;
  item_name: string;
  item_category: string;
  price: number;
  quantity?: number;
}

Validate before you ship, not after

A lightweight runtime assertion in non-production builds catches more schema drift than a code review ever will — it fails loudly the moment a field goes missing, instead of three weeks later in a QBR.