Before you start
- The data layer in place. The data layer guide is the first prerequisite: the shop's developers need to be able to push structured objects to the data layerA structured object on a web page that passes values to a tag manager for tags to use. on each template before the tag fires.
- Events and parameters understood. The events and parameters guide is the second: how GA4 events carry parameters, which parameters are collected automatically, and the difference between an event parameterA named value sent with an analytics event that describes it, such as a page location, form name or item price. and an item parameter.
- One implementation route. Decide whether the shop will use this Tag Manager approach, a direct Google tag implementation, or a platform's native integration. Use one. Many wrong revenue figures come from two routes running together.
- A product field inventory. For each template (listing, product, basket, checkout, confirmation), write down which product attributes the page can expose: identifier, name, brand, category, variant, price, and whether the price shown includes tax.
- A test environment and a test order. Tag Manager preview and GA4 DebugView work on production, but a staging siteA private copy of a website or tool where changes are tested before release, kept behind access control and out of search and production analytics. and a way to place and refund a real test order make the purchase step safe to check.
- Agreement on currency and value. Pick the currency code the site will send and decide once whether event values include tax and shipping; the developer guide's convention is item price times quantity, with tax and shipping sent in their own parameters.
Map the shopping funnel to the recommended events
Walk the shop as a customer and note each stage: a category or search listing, a product page, the basket, the start of checkout, the shipping and payment stages, the confirmation page, and the refund process in the back office. Each stage maps to a documented GA4 event, listed in the reference table below. The listing and product templates are the same ones the category and product pages guide describes from the search side, which helps when asking developers where in the template code each push belongs. Decide now which events are in scope for the first release. A sensible minimum is product view to purchase; promotions, wishlists and the basket view can follow once the core set is verified.
Agree the items array contract
Every e-commerce event carries an
itemsarray, and every object in it uses the same documented fields:item_idoritem_name(one is required, send both), plusitem_brand,item_categoryand its numbered siblings,item_variant,price,quantity,discount,coupon,index,item_list_id,item_list_nameandlocation_idwhere they apply. Write this as a one-page contract with the developers: the source of each field in the catalogue, the format of the identifier (the same SKU or product ID everywhere, never the name on one template and the SKU on another), the price as a plain number in the agreed currency, and the quantity as a whole number. Consistency matters more than completeness, because item reports group on these values and a brand spelled two ways becomes two brands.Instrument listings with view_item_list and select_item
On category pages, search results and any carousel of products, push
view_item_listwith the list'sitem_list_idanditem_list_nameand the items shown, each with itsindexposition. When a shopper clicks a product in the list, pushselect_itemwith the same list identifiers and the single item chosen. These two events power the item list reports, which show which placements lead to views and purchases. Lists that render more items as the shopper scrolls should push additionalview_item_listevents for the newly rendered batch rather than one event for the whole page, and the list name should be the merchandising name a buyer recognises, not a template identifier.Instrument the product page with view_item
On the product detail template, push
view_itemwithcurrency,valueset to the item price, and anitemsarray containing the product with as many of the contract fields as the page can supply. If the page has variant selectors, decide whether a variant change pushes a newview_itemor updates the data layer silently; the developer guide treats a view as a view of the page, and in practice one event per page load with the default variant is the cleaner choice. Make sure the push happens before the Tag Manager container evaluates the trigger; a push that lands after the page view has fired is lost unless it is tied to its own event name, which is why the data layer guide insists on pushing aneventkey.Track basket changes with add_to_cart and remove_from_cart
Push
add_to_cartwhen a product is added, withcurrency,valueas the price times the quantity added, and the item with itsquantity. Pushremove_from_cartsymmetrically when a line is removed or its quantity reduced, with the quantity removed. Quantity changes inside the basket are the usual source of errors: an increment from one to two should send an add of one, not an add of two. If the basket page itself is a meaningful stage for the business, pushview_cartwith the full contents. These events drive the purchase journey report's add-to-basket step and the item-level "added to basket" metric, so an implementation that only tracks the product page's add button and misses the quick-add on listings will understate the step.Mark the start of checkout with begin_checkout
On the first checkout page, or when the checkout button is clicked for a single-page checkout, push
begin_checkoutwithcurrency,valueas the basket's item total, theitemsarray of the whole basket, andcouponif a code is already applied. This is the first step of the checkout journey report and the point from which checkout abandonment is measured. Guest and signed-in flows should both fire it; a flow that sends the event only after login hides the people who leave at the login wall. If the checkout is hosted on another domain, cross-domain measurementConfiguring analytics so a visit that moves between a business's own domains stays one session. must be configured in the data stream before this step, or the session will restart and the funnel will show checkout starting from Referral.Add the checkout stages with add_shipping_info and add_payment_info
Push
add_shipping_infowhen the shopper submits a delivery method, carryingshipping_tierwith the chosen option, andadd_payment_infowhen a payment method is chosen, carryingpayment_type. Both include the samecurrency,valueanditemsas the checkout start. These two events complete the checkout journey report, which then shows where between shipping, payment and purchase the shop loses people. Avoid firing them on page load of the shipping and payment steps if the shopper has not yet made a choice; fire on the action. Where the checkout is a single page with sections, fire each event when its section is completed, which usually means on the continue button rather than on field blur.Send purchase with a transaction identifier
On the confirmation page, push
purchasewithtransaction_idset to the order number,currency,valueas the order's item total,tax,shipping,couponandaffiliationwhere relevant, and the fullitemsarray with final prices and quantities. The identifier is documented as the field that helps GA4 avoid counting a purchase twice; treat it as a safety net rather than a licence to fire on every reload, because event counts and downstream destinations such as a Google Ads import can still see the repeat. Guard the push server-side or with a flag so a refreshed confirmation page, a bookmarked one or a return from a payment provider does not send the order again. The value convention and the identifier set here are what GA4's average order value is built from, as the glossary entry on AOV in GA4 explains. Keep test orders out of production or filter them by a developer traffic rule. Once revenue flows, the ROAS calculator turns the purchase values and campaign spend into the ROASRevenue generated per unit of ad spend. figures the media team will ask for.Record refunds
Refunds usually happen in the back office rather than in the browser, which makes
refundthe event most implementations skip. For a full refund, sendrefundwith the originaltransaction_id,currencyandvalue; for a partial refund, include theitemsarray with only the refunded lines and quantities. Because there is no page to push from, this event is often sent through the Measurement Protocol from the order management system, or batched daily by a developer; both are legitimate as long as the identifier matches the original purchase. Without refunds, GA4 revenue overstates the shop's net figure permanently and the CVRShare of visits or clicks that convert. by campaign looks better than the finance team's view. Decide early whether refunds are in scope and document the choice in the contract if they are not.Build the Tag Manager tag and trigger
In the container, create one GA4 event tag whose event name is read from the built-in Event variable, so the data layer's
eventkey becomes the GA4 event name unchanged. Enable the tag's option to send e-commerce data with the data layer as the source, which makes the tag read theecommerceobject and forwarditems,currency,valueand the other parameters without mapping each one by hand. Create a custom event trigger whose event name matches the e-commerce event names, either listed or with a regular expression, and attach it. Before each push, the site should pushecommerce: nullto clear the previous object so fields from an earlier event do not leak into the next; the data layer guide explains why the merge behaviour makes this necessary. Publish to a workspace, not straight to live, and test in preview.Verify in DebugView and the reports
Open Tag Manager preview and walk the journey from listing to purchase with a test order. At each stage, confirm the data layer tab shows the push with the expected
items, that the GA4 tag fired once and only once, and that the outgoing request carries the item fields. Then open GA4 DebugView, select the debug device, and inspect each event's parameters and items; a missing field is usually a template that does not expose it rather than a tag problem. Place and refund a test order and checkpurchaseandrefundarrive with the same identifier. After processing, read the ecommerce purchases report for the item rows, the purchase journey and checkout journey reports for the funnel steps, and reconcile a closed day against the shop's order list; if that day does not reconcile, the guide to GA4 revenue that does not match the shop's orders sorts the differences by cause. The conversion analytics hub covers what to do with the funnel once it is trustworthy.
Event reference table
| Event | When it fires | Key parameters | Report it feeds |
|---|---|---|---|
view_promotion / select_promotion | A promotion banner is shown or clicked | promotion_id, promotion_name, creative_name, creative_slot, items | Promotions report |
view_item_list | A list of products is rendered | item_list_id, item_list_name, items with index | Item list performance |
select_item | A product is clicked in a list | item_list_id, item_list_name, one item | Item list performance |
view_item | A product page is viewed | currency, value, items | Ecommerce purchases (items viewed), purchase journey |
add_to_wishlist | A product is saved for later | currency, value, items | Item metrics |
add_to_cart / remove_from_cart | A line is added to or removed from the basket | currency, value, items with quantity | Purchase journey, items added to basket |
view_cart | The basket page is viewed | currency, value, items | Purchase journey (optional step) |
begin_checkout | Checkout starts | currency, value, coupon, items | Purchase journey, checkout journey |
add_shipping_info | A delivery option is chosen | shipping_tier, currency, value, items | Checkout journey |
add_payment_info | A payment method is chosen | payment_type, currency, value, items | Checkout journey |
purchase | The order is confirmed | transaction_id, currency, value, tax, shipping, coupon, items | Revenue, transactions, item revenue, all funnels |
refund | An order is refunded in full or in part | transaction_id, currency, value, items for partial | Refund metrics |
Two pushes from a bicycle retailer's templates
A bicycle shop's product template pushes view_item for a gravel bike priced at £1,250, and its
confirmation page pushes purchase for an order of that bike plus two inner tubes at £6.50 each, with
£12 shipping and £252.60 tax (20% of the item total) recorded separately, with no discount code applied. The
value on the purchase is the item total of £1,263.00, following the developer guide's convention, and the
order number GB-204417 is the transaction_id. The pushes below are what the developers ship; the clearing push before each one stops
the tubes from appearing on the next product view. In DebugView the purchase shows two item rows (three
units) and one transaction_id, and the ecommerce purchases report lists the bike with item revenue of
£1,250 and the tubes with £13 the following day.
window.dataLayer = window.dataLayer || [];
dataLayer.push({ ecommerce: null });
dataLayer.push({
event: "view_item",
ecommerce: {
currency: "GBP",
value: 1250.00,
items: [{
item_id: "BK-GRV-56",
item_name: "Ridgeline Gravel Bike",
item_brand: "Ridgeline",
item_category: "Bikes",
item_category2: "Gravel",
item_variant: "56cm / Slate",
price: 1250.00,
quantity: 1
}]
}
});
dataLayer.push({ ecommerce: null });
dataLayer.push({
event: "purchase",
ecommerce: {
transaction_id: "GB-204417",
currency: "GBP",
value: 1263.00,
tax: 252.60,
shipping: 12.00,
items: [
{ item_id: "BK-GRV-56", item_name: "Ridgeline Gravel Bike", item_brand: "Ridgeline", item_category: "Bikes", item_category2: "Gravel", item_variant: "56cm / Slate", price: 1250.00, quantity: 1 },
{ item_id: "TB-700-32", item_name: "Inner Tube 700x32", item_brand: "Ridgeline", item_category: "Parts", price: 6.50, quantity: 2 }
]
}
});
When orders arrive in the shop but no purchases or no revenue reach the property, the diagnosis on a GA4 purchase event that is not tracking follows a test order from the push to the report. Once the events are verified, the guide to product and merchandising analysis in GA4 reads the item lists, promotions and product funnels they produce.
Verify it worked
- Walk the journey from listing to purchase in Tag Manager preview. Each stage should show one data layer push with the expected
items, and the GA4 tag should fire once. - Open DebugView after a test order. The purchase should show every ordered line and one
transaction_id, as in the bicycle example. - Compare the purchase
valuewith the item total. Tax and shipping should sit in their own parameters. - Reload the confirmation page. No second purchase should appear. Then refund the test order and confirm
refundarrives with the same identifier. - After processing, read the purchase and checkout journey reports. A closed day should reconcile with the shop's order list.
If it goes wrong
- Revenue is double the shop's order total. Two implementation routes are probably running, or the purchase is resent on reload. Keep one route and guard the push.
- The item reports show two products for one. Identifiers probably differ between templates. Use the same SKU or product ID everywhere.
- An event carries items from the previous event. The
ecommerce: nullclear is probably missing. Push it before every e-commerce event. - The funnel shows checkout starting from Referral. The checkout is probably on another domain. Configure cross-domain measurement in the data stream.
- A field is missing in DebugView. The template may not expose it, or the push landed late. Ask the developers to expose it and keep the
eventkey.
Next steps
- Read the data layer guide when pushes arrive late or leak fields; it explains the event key and the merge behaviour.
- Read the events and parameters guide before adding custom fields.
- Read the category and product pages guide when a missing field points at a listing or product template.
- Read the conversion analytics hub once a closed day reconciles, to choose which funnel step to improve first.
Common mistakes
- Two implementations at once. A platform integration and a Tag Manager tag both sending
purchasedoubles revenue from day one. - Different identifiers per template. A SKU on the product page and a database ID at checkout make the item reports show two products for one.
- Purchase on page load without a guard. Reloads, bookmarks and payment-provider returns resend the order.
- Value conventions that drift. Tax in on one template and out on another; pick the convention and write it down.
- Missing the
ecommerce: nullclear. Items from the previous event leak into the next push. - Checkout on another domain without cross-domain setup. The funnel restarts from Referral at checkout.
- Skipping refunds. Revenue overstates the net figure for ever.
- Verifying only in preview. DebugView and a reconciled closed day against the order list are the test that counts; the GA4 hub links the debugging and checklist pages that make that routine.
