If you need more control over your tracking setup, you can add your own Google Tag Manager (GTM) container. Your GTM container loads on your storefront in addition to Understory's own container. Use it to add tags Understory doesn't send, such as other ad platforms, email marketing or heatmap tools.
This is an advanced option. Your own GTM container runs next to Understory's built-in tracking for GA4, Google Ads and Meta Pixel, so only add tags for tools Understory does not already send to.
How to Enable Your Own GTM Container
Requirements: Admin access and an existing Google Tag Manager account.
Go to Marketing > Overview — in the left-hand menu of your Backoffice, then open the Settings tab
Find the Google Tag Manager section — it's listed alongside GA4, Google Ads, and Meta Pixel
Enter your Container ID — in the format
GTM-XXXXXXX(find this in your GTM account under Admin > Container Settings)Toggle the switch to Active — then click Save in the Google Tag Manager section. The Save button appears only in a section that has unsaved changes, so you may need to save twice: once for the Container ID and once for the toggle**
Once saved, your GTM container loads on your storefront in addition to Understory's own container.
What Changes When You Use Your Own Container
Good to know:
Your GTM container loads in addition to Understory's own container — both containers load at the same time
The GA4, Google Ads and Meta Pixel integrations in Marketing > Overview > Settings keep working alongside your container. Do not send to the same GA4 property, Meta pixel or Google Ads conversion from your own container — every event would be counted twice. Understory will not save your container settings if it detects this; turn the destination off either in Understory or in your container
Still works:
Your storefront continues to push all tracking events to the
dataLayer— your GTM container picks these up automaticallyUTM campaign parameters are still captured and preserved
Understory's internal analytics (used for your dashboard metrics) continue to work independently
You are now responsible for:
Creating and configuring the tags you add to your GTM container
Setting up cookie consent mode
Configuring conversion tracking
Testing that your tags fire correctly
Quick Start with GTM Templates
We provide importable GTM container templates with pre-configured tags, triggers, and variables. Choose the template that matches your setup:
Storefront template — for customers who use their own GTM container on the Understory storefront
Widget template — for customers who embed the Understory booking or gift card widget on their own website and want to track widget interactions
The template files are not currently available for download from the Backoffice. Reach out to us in the chat window and we'll send you the JSON file you need.
You can import both if you use the storefront and widgets together — the shared variables and Google Tag configuration have the same names, so GTM merges them automatically.
What's included
Each template imports an Understory folder into your GTM container. Everything is prefixed with "Understory - " so you can easily identify imported items alongside your own tags.
Storefront template:
Type | What's included |
Tags | Google Tag (GA4 config), GA4 Event tags for |
Triggers | Custom event triggers for all storefront events including |
Variables | Data Layer variables for ecommerce data, the booked session ID, and a placeholder GA4 Measurement ID |
Widget template:
Type | What's included |
Tags | Google Tag (GA4 config), GA4 Event tags for |
Triggers | Custom event triggers for |
Variables | Data Layer variables for ecommerce data and a placeholder GA4 Measurement ID |
How to import
Get the template file — save the template JSON file to your computer
Open your GTM container — go to Admin > Import Container
Choose the file — select the template JSON file
Select "Merge" — choose "Rename conflicting tags, triggers, and variables" to safely add the Understory items alongside your existing setup
Review and confirm — GTM shows a summary of what will be added
After importing
Open the variable "Understory - GA4 Measurement ID" — replace
G-XXXXXXXXXXwith your actual GA4 Measurement IDPreview and test — use GTM's Preview mode to verify events fire correctly
Publish — when everything looks good, publish your container
If you imported an earlier version of this template before, you may end up with unused Understory - DLV - receipt.* variables alongside the new ones. They are harmless, but you can safely delete them once nothing references them.
Storefront DataLayer Events
Your storefront pushes the following events to the dataLayer. These follow the standard GA4 ecommerce schema.
Page Views
page_view — Fires on every page navigation.
Browsing Events
select_item — A visitor clicks an experience card in your storefront's experience listing.
This event fires only from that listing. It does not fire when a visitor opens an experience page from a direct link, search results, your own website, or the embedded widget. If most of your traffic links straight to experience pages, expect this event to be rare compared to view_item — that is normal, not a tracking fault.
Property | Example Value |
item_list_id |
|
item_list_name |
|
items[].item_id | Experience ID |
items[].item_name | Experience name |
items[].affiliation |
|
items[].item_category |
|
view_item — A visitor opens an experience detail page.
Property | Example Value |
currency |
|
value | Total price |
items[].item_id | Experience ID |
items[].item_name | Experience name |
items[].affiliation |
|
items[].item_category |
|
Booking Flow Events
Identifying the booked session. One experience runs many sessions, so the experience ID alone cannot tell a Tuesday sitting apart from a Saturday one. The experience_event_id property names the specific session, which lets you follow a single session all the way through to purchase.
Experiences booked on open hours have no session until the booking is actually made, so the property is absent on their add_to_cart and begin_checkout events and appears for the first time on on_receipt. It is always absent for gift cards and punch cards. When there is no session, the property is left out entirely rather than sent empty.
add_to_cart — A visitor selects guests and proceeds in the booking flow.
Property | Example Value |
currency |
|
totalPrice | Total price |
experience_event_id | The selected session's ID (scheduled experiences only) |
items[].item_id | Experience ID |
items[].item_name | Experience or variant name |
items[].affiliation |
|
items[].item_category |
|
items[].item_variant | Variant ID (in the form |
items[].price | Unit price |
items[].quantity | Number of guests |
begin_checkout — A visitor starts the payment process.
Property | Example Value |
currency |
|
value | Checkout total |
experience_event_id | The booked session's ID (scheduled experiences only) |
items[].item_id | Variant ID |
items[].item_name | Ticket type name (for example |
items[].affiliation |
|
items[].item_category |
|
items[].item_category2 | Experience name |
items[].item_category3 | Experience ID |
items[].price | Unit price |
items[].quantity | Number of guests |
Gift card and punch card checkouts
Gift cards and punch cards push their own begin_checkout event with a single item. They have no session, so experience_event_id is never sent for them.
Property | Gift card | Punch card |
value | Total charged (including fees) | Total charged (including fees) |
items[].item_id | Your company ID | Punch card type ID |
items[].item_name |
|
|
items[].item_category |
|
|
items[].price | Gift card amount | Punch card price |
items[].quantity |
|
|
Purchase Event
on_receipt — A purchase is completed. This is the most important event for conversion tracking.
Important: This event is named on_receipt, not the standard GA4 purchase. The GTM template handles this mapping for you — the included "Understory - GA4 Event - purchase" tag listens for on_receipt and sends it to GA4 as a purchase event. If you're setting this up manually, create a custom event trigger for on_receipt.
Property | Example Value |
transaction_id | Unique receipt ID (use this for conversion deduplication) |
experience_event_id | The booked session's ID (bookings only — not sent for gift cards or punch cards) |
receiptId | Receipt ID |
receiptCreatedDate | When the order was created |
currency |
|
value | Order total (excluding gift card payments) |
items[].item_id | Variant ID (or voucher ID for gift cards) |
items[].item_name | Item name |
items[].affiliation |
|
items[].item_category |
|
items[].item_category2 | Item name |
items[].item_category3 | Experience ID |
items[].price | Unit price (VAT inclusive) |
items[].quantity | Quantity |
items[].currency |
|
items[].vat_rate | VAT rate (e.g. |
items[].vat_amount | VAT amount |
Also available under payload. Everything in the table above except experience_event_id is sent a second time, nested under a payload key, with the two category fields spelled item_category_2 and item_category_3. That was the original format for this event and it still works, so existing container mappings need no changes. New setups should use the properties in the table above — they match every other event and GA4's own purchase shape.
Note that item_category2 means something different on this event than it does on begin_checkout: here it is the line item's name, while on begin_checkout it is the experience name. Only item_category3 (the experience ID) means the same thing on both events, so use that one when joining the funnel together.
Other Events
private_request_submitted — A visitor submits a private event request form.
Property | Example Value |
formattedDate | Requested date |
participants | Number of participants |
Embedded Widget DataLayer Events
If you use the Understory booking or gift card widget on your own website, the widgets also push ecommerce events to the dataLayer. These events are prefixed with understory_ to avoid interfering with any existing tracking you have on your site.
The widget events use the same item data structure as the storefront events (currency, value, items with item_id, item_name, affiliation, etc.), so you can process them in the same way.
Important: The widgets do not load GTM — they only push events to the dataLayer. If you have GTM installed on your website, these events are picked up automatically. If you don't have GTM, the events are safely ignored.
Booking Widget Events
understory_view_item — The widget loads and displays an experience.
Property | Example Value |
currency |
|
value |
|
items[].item_id | Experience ID |
items[].item_name | Experience name |
items[].affiliation |
|
items[].item_category |
|
understory_add_to_cart — A visitor selects guests and proceeds to the confirmation step.
Property | Example Value |
currency |
|
value | Total price |
items[].item_id | Experience ID |
items[].item_name | Experience and variant name |
items[].affiliation |
|
items[].item_category |
|
items[].item_variant | Variant ID |
items[].price | Unit price |
items[].quantity | Number of guests |
understory_begin_checkout — A visitor confirms their booking and proceeds to payment.
Property | Example Value |
currency |
|
value | Checkout total |
items[].item_id | Experience ID |
items[].item_name | Experience and variant name |
items[].affiliation |
|
items[].item_category |
|
items[].item_variant | Variant ID |
items[].price | Unit price |
items[].quantity | Number of guests |
Gift Card Widget Events
understory_view_item — The gift card widget loads.
Property | Example Value |
currency |
|
value |
|
items[].item_id |
|
items[].item_name |
|
items[].affiliation |
|
items[].item_category |
|
understory_begin_checkout — A visitor proceeds to payment for a gift card.
Property | Example Value |
currency |
|
value | Gift card amount |
items[].item_id |
|
items[].item_name |
|
items[].affiliation |
|
items[].item_category |
|
items[].price | Gift card amount |
items[].quantity |
|
Using widget events in GTM
The understory_ prefix means these events won't accidentally trigger tags you've set up for other products on your site. The widget GTM template includes triggers that listen for the prefixed event names and forward them to GA4 as standard ecommerce events (view_item, add_to_cart, begin_checkout).
DataLayer Variables
These variables are pushed to the dataLayer before your GTM container loads on the storefront, so they're available to all your tags:
Variable | Description |
| Your Understory company ID |
| Your GA4 Measurement ID (if configured) |
| Domains for cross-domain tracking (includes your storefront domain automatically) |
Campaign parameters. If a visitor arrives with campaign parameters in the URL, the storefront stores them and merges them into every event it pushes, including page_view. This covers campaignSource, campaignGclid, and any utm_ parameters you use. You can read them with Data Layer variables like any other property, which is useful for attribution on your conversion tags.
Tips for Setting Up Conversion Tracking
Google Ads Conversions
Create a Google Ads Conversion Tracking tag in your GTM container
Set the trigger to fire on the
on_receipteventUse the
transaction_idproperty as the Order ID — this prevents duplicate conversions from being countedMap
valueto the conversion value andcurrencyto the currency (both are also available aspayload.valueandpayload.currency)
Google Analytics 4
If you're using the Understory GTM templates, GA4 is already configured — just replace the Measurement ID placeholder. If you're setting up manually:
Create a Google Tag using your Measurement ID
Add GA4 Event tags for each ecommerce event you want to track
Create Data Layer variables to extract the event properties (currency, value, items) and map them as event parameters
Meta Pixel
Add the Meta Pixel base tag to your container
Map the storefront events to Meta standard events — for example,
on_receipt→Purchase,begin_checkout→InitiateCheckout,view_item→ViewContent
Cookie Consent
When you use your own GTM container, you manage consent mode. The storefront reads consent status from the dataLayer, so if you implement Google Consent Mode v2 in your container, it will be respected across all tracking.
Did this answer your question? If not, please reach out to us in the chat window at the bottom to the right, and we'll be happy to help 🤗
