GA4 ecommerce events reference

What this is

A field-level reference for the GA4 recommended ecommerce events — the event parameters, item-object fields, and revenue rules for the full purchase funnel. Use it to instrument or audit view_item_list through purchase and refund without re-reading the vendor docs.

Event reference

Typical funnel order: view_item_list → select_item → view_item → add_to_cart → view_cart → remove_from_cart → begin_checkout → add_shipping_info → add_payment_info → purchase → refund. Non-linear events: add_to_wishlist, view_promotion, select_promotion.

Notes: shipping_tier is a delivery option (e.g. Ground, Air, Next-day); payment_type is the chosen method of payment; shipping and tax on purchase/refund are monetary costs associated with the transaction; customer_type is new or returning.

Item object fields

Each object in the items array. One of item_id or item_name is required; every other field is optional.

Revenue parameter rules

Limits

The docs fetched do not specify a maximum length or format constraint for transaction_id, item_id, or string parameter values; those are governed by separate GA4 event/parameter limit docs.

Gotchas

1. Symptom Purchase fires in DebugView but reports show zero revenue. Cause value is absent, undefined, zero, or sent as a string ('49.99' or '$49.99'). Fix Send value as a numeric type and confirm a positive number appears under the event in DebugView before shipping.
2. Symptom Revenue metrics are not computed even though value is present. Cause currency is missing, empty, or a symbol ($) instead of a 3-letter ISO 4217 code. Fix Send currency as a valid ISO 4217 code (USD, EUR, GBP); GA4 requires it whenever value is set.
3. Symptom Value or currency comes through as zero / undefined intermittently. Cause A GTM tag fires on DOM Ready / Page Load before the ecommerce dataLayer push has executed, so the tag reads empty values. Fix Trigger the tag on the ecommerce dataLayer Custom Event keyed to the event name, not on Page View / DOM Ready.
4. Symptom Duplicate purchases inflate transaction counts and revenue. Cause transaction_id is missing, or the confirmation page can be reloaded and re-fires purchase. Fix Always send a stable, unique transaction_id per order; GA4 dedupes on it.
5. Symptom Events arrive but item-level reports (item revenue, item refunds) are empty. Cause The items array is omitted, items lack both item_id and item_name, or refund is sent without items. Fix Include an items array with at least item_id or item_name, and include item info in refund to get item-level refund metrics.
6. Symptom List or promotion attribution is wrong or missing. Cause Event-level item_list_id / item_list_name are ignored when also set at item level, and promotion events need an items array for some reports. Fix Set list and promotion IDs consistently at one scope, and include the items array on promotion events.
7. Symptom Reported revenue is higher than actual order totals. Cause value included shipping and tax, or was set to a per-item price instead of the sum of price * quantity. Fix Set value to the sum of price * quantity for all items, exclude shipping and tax, and send shipping and tax as their own parameters.

Quick recipes

// Full item object: every documented field populated.
gtag('event', 'add_to_cart', {
  currency: 'USD',
  value: 30.03, // sum of price * quantity, excluding shipping and tax
  items: [{
    item_id: 'SKU_12345',
    item_name: 'Stan and Friends Tee',
    affiliation: 'Google Merchandise Store',
    coupon: 'SUMMER_FUN',
    discount: 2.22,
    index: 0,
    item_brand: 'Google',
    item_category: 'Apparel',
    item_category2: 'Adult',
    item_category3: 'Shirts',
    item_category4: 'Crew',
    item_category5: 'Short sleeve',
    item_list_id: 'related_products',
    item_list_name: 'Related Products',
    item_variant: 'green',
    location_id: 'ChIJIQBpAG2ahYAR_6128GcTUEo',
    price: 10.01,
    quantity: 3
  }]
});

// The four fields audits check first: transaction_id, value, currency, items.
gtag('event', 'purchase', {
  transaction_id: 'T_12345', // required: deduplication
  currency: 'USD',           // required if value is set (ISO 4217)
  value: 30.03,              // number: sum of price * quantity, no shipping/tax
  shipping: 4.99,            // sent separately, not folded into value
  tax: 2.40,
  coupon: 'SUMMER_FUN',
  items: [{ item_id: 'SKU_12345', item_name: 'Stan and Friends Tee', price: 10.01, quantity: 3 }]
});

// currency is optional here; item_list_id/name apply to every item in the list.
gtag('event', 'view_item_list', {
  item_list_id: 'related_products',
  item_list_name: 'Related Products',
  items: [
    { item_id: 'SKU_12345', item_name: 'Stan and Friends Tee', index: 0 },
    { item_id: 'SKU_12346', item_name: 'Google Grey Tee', index: 1 }
  ]
});

// Include items to get item-level refund metrics; transaction_id matches the purchase.
gtag('event', 'refund', {
  transaction_id: 'T_12345',
  currency: 'USD',
  value: 10.01,
  items: [{ item_id: 'SKU_12345', quantity: 1 }]
});

// GTM pattern: push after order data exists; fire the tag on this Custom Event,
// not on Page View / DOM Ready, or value and currency read empty.
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T_12345',
    currency: 'USD',
    value: 30.03,
    tax: 2.40,
    shipping: 4.99,
    items: [{ item_id: 'SKU_12345', item_name: 'Stan and Friends Tee', price: 10.01, quantity: 3 }]
  }
});

// Event-level coupon is independent of any item-level coupon.
gtag('event', 'begin_checkout', {
  currency: 'USD',
  value: 30.03,
  coupon: 'SUMMER_FUN',
  items: [{ item_id: 'SKU_12345', item_name: 'Stan and Friends Tee', price: 10.01, quantity: 3 }]
});

Related

• Hub: GA4 implementation guides
• GA4 event naming cheat sheet
• GA4 limits reference

Sources

• Measure ecommerce — Google Analytics (read 2026-07-20)
• Event reference (gtag.js) — Tag Platform (read 2026-07-20)
• Recommended events — Google Analytics (read 2026-07-20)