Ecommerce Enriched Items — GTM Web Variable Template

Returns the current ecommerce.items array enriched with list / promotion attribution previously captured by the Ecommerce Attribution Capture tag.

Drop-in replacement for your raw data-layer items variable as the items parameter on GA4 Event tags for add_to_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, refund.

Why this exists

GA4's item-level attribution fields (item_list_id, item_list_name, promotion_id, promotion_name) are typically only present on list/promotion events. This variable joins them back onto downstream ecommerce events so you can build true item-level "product listing" and "promotion" attribution reports and pass the same attribution to Meta CAPI, Google Ads, and BigQuery.

What it does

1. Reads ecommerce.items from the data layer (path is configurable).
2. Reads the stored attribution blob from localStorage.
3. For each item, looks up its stored attribution by item_id (or item_name as fallback).
4. Merges stored attribution into the item (respecting your Overlay / Override mode and per-field toggles).
5. Returns the enriched array. If no attribution is stored, the original items array is returned unchanged.

Required: pair with the Attribution Capture tag

This variable is the read side of the storage contract written by the companion Ecommerce Attribution Capture tag. Both must be installed, and both must share the same localStorage key.

Fields

Field	Type	Default
Items data layer path	Text	ecommerce.items
localStorage key	Text	bdt_ecom_attr_v1
TTL (minutes) — stale reads filter	Number	30
Enrichment mode	Radio	Overlay (recommended) / Override
Enrich item_list_id	Checkbox	ON
Enrich item_list_name	Checkbox	ON
Enrich promotion_id	Checkbox	ON
Enrich promotion_name	Checkbox	ON
Enrich page_location	Checkbox	ON
Enrich page_type	Checkbox	ON
Optional diagnostic parameter name	Text	empty (e.g. attribution_source)
Debug mode	Checkbox	OFF

Enrichment mode

• Overlay (recommended): data-layer values on the item always win. Stored attribution only fills fields that are empty on the item. Safest for round-tripping events that legitimately already carry item-level attribution.
• Override: stored attribution always wins over the item's data-layer value. Use only when you know the developers push attribution inconsistently and you want the captured truth to dominate.

Diagnostic parameter

If you set Optional diagnostic parameter name to e.g. attribution_source, every enriched item gets that extra parameter populated with the event name that produced the attribution (select_item, view_item_list, …). Useful in audits and BigQuery queries. Off by default to keep the GA4 schema clean. If you enable this, register the parameter as a GA4 custom dimension (scope: item) to see it in reports.

Permissions

• access_local_storage — read-only on keys matching bdt_ecom_attr_*
• read_data_layer — ecommerce, ecommerce.*
• logging — debug environment only

Installation

1. Install from the GTM Community Template Gallery (search for "Ecommerce Enriched Items"), or import template.tpl manually.
2. Install the companion Ecommerce Attribution Capture tag (separate template).
3. Create a new User-Defined Variable → type = Ecommerce Enriched Items. Name it something like DLV - ecommerce.items (enriched).
4. On each GA4 Event tag for add_to_cart, view_cart, begin_checkout, add_shipping_info, add_payment_info, purchase, and refund, set the items event parameter value to this new variable instead of the raw dataLayer items variable.
5. Verify in Preview Mode: trigger select_item on a category page, navigate to the PDP, and fire add_to_cart. The add_to_cart hit in GA4 DebugView should now carry items[0].item_list_id, item_list_name, page_location and page_type.

Fallback behavior

If any of the following are true for a given item, the item is returned unchanged (safe fallback):

• No stored attribution blob.
• No entry for the item's item_id (or item_name fallback).
• Stored entry is older than the configured TTL.
• Item has no item_id and no item_name.

License

Apache 2.0. See LICENSE.

Issues / contributions

File issues on this GitHub repository. Issues must remain enabled per Gallery policy.