dataLayer specification template: a free CSV developers can build from

This dataLayer specification template turns "please add a dataLayer for GA4" into a list a developer can build in a day: one row per key, with the page, the moment to push, the type, whether it is required and an example value. Download the dataLayer specification template (CSV). It opens in Google Sheets and Excel, and comes filled in for page-level data, four GA4 ecommerce events and a lead form.

What is in the dataLayer specification template?

65 example rows, grouped by event:

• Page-level data pushed above the GTM container snippet: page_type, user_status, site_language.
• view_item, add_to_cart, begin_checkout and purchase, each with the ecommerce clear, the ecommerce keys and every ecommerce.items[] field: item_id, item_name, item_brand, item_category, item_variant, price, discount and quantity.
• generate_lead with value, currency, form_id and lead_type.

The event names and ecommerce structure follow GA4's recommended events, so a GA4 Event tag in GTM can send the ecommerce object as is, with Send Ecommerce data ticked and the source set to Data Layer. For the reasoning behind each rule, read the dataLayer spec guide.

What does each column mean?

How do you fill it in?

1. Start from the measurement plan. Every event in the spec should trace back to a row in the measurement plan template. If it does not, leave it out.
2. Write the firing moment as a result. "When the server returns a success response for the demo form" is buildable. "When the form is submitted" is ambiguous.
3. Keep the GA4 shapes for ecommerce. Do not rename item_id to sku or move items out of ecommerce. GTM then needs no remapping.
4. Give every key a type and allowed values. price is a number in major units, not a formatted string. lead_type is one of demo, trial, contact, newsletter.
5. Add a copy-paste push per event in the document that goes with the sheet, built from the rows:

dataLayer.push({ ecommerce: null });  // Clear the previous ecommerce object.
dataLayer.push({
  event: "add_to_cart",
  ecommerce: {
    currency: "EUR",
    value: 59.8,
    items: [{
      item_id: "SKU_1042",
      item_name: "Merino crew sock",
      item_brand: "Northwind",
      item_category: "Socks",
      item_variant: "grey",
      price: 29.9,
      quantity: 2
    }]
  }
});

1. Add an acceptance test per event: a page, an action, and the exact object expected in window.dataLayer. For generate_lead, a valid test submission produces exactly one push, and a validation error produces none.

Which rules should sit at the top of the spec?

Google's data layer guide for Tag Manager has a few rules that cause most implementation bugs when ignored. Repeat them above the table:

• Initialise once, high in the page, with window.dataLayer = window.dataLayer || []; above the container snippet.
• Only push. Never reassign dataLayer after GTM has loaded, because that disconnects GTM from the array.
• The object is dataLayer, with a capital L.
• Use the same key for the same concept on every page.
• Event names are case sensitive, start with a letter, use only letters, numbers and underscores, and are 40 characters at most.

What are the common mistakes?

• Not clearing ecommerce. GTM merges pushes into one data model, so keys from add_to_cart can leak into purchase. The template has a clear row before every ecommerce event.
• Shipping and tax inside value. value is the sum of price times quantity, with tax and shipping in their own keys.
• Line totals as price. price is the unit price after discount; the unit discount goes in discount, and GA4 does not subtract it for you.
• A hardcoded or empty transaction_id. It must be the shop's real order number, in the same format everywhere, and never contain personal data. The full list of revenue errors is in GA4 ecommerce tracking mistakes.
• Purchase on every confirmation page load. Reloads and revisits from the order email count again. Push once per order.
• Amounts in minor units or as formatted strings. Send 72.05, not 7205 or "72,05".
• Currency hardcoded on a multi-currency shop. Send the three-letter code the customer paid in.
• Personal data in the lead push. Name, email, phone and free-text fields never go into the dataLayer event.

Consent and single-page apps behave differently from ordinary events, so give each its own short section in the document rather than rows in the sheet. The dataLayer glossary entry covers the basics for anyone new to the concept.

Next step

Give the filled-in sheet to your developer, then connect the site to Tracking Whisper: it checks the pushes on key pages in a real browser against the spec and builds the matching tags in its own GTM workspace for a person to approve. See our Google Tag Manager integration.