Next Commerce
Tracking

Google Tag Manager

Send your campaign's events to your own Google Tag Manager container, and build tags on them.

Google Tag Manager (GTM) does not report anything by itself. It is a container for your own tags. Your campaign sends its events to GTM, and the tags you build decide which platforms hear about them.

Use GTM when you want to manage tags yourself, or for a platform that has no guide in this section.

Before you start

  • A GTM web container and its ID, which looks like GTM-XXXXXXX.
  • A campaign that is ready for tracking. See Set up tracking.

The Google Tag Manager app you set up under Apps in your NEXT dashboard only adds its script to your Storefront. It is not added to your Campaigns, so follow this page to add GTM to your campaign.

Set up

Setup has two parts, and you need both.

  1. In _data/campaigns.json, add your container ID to your campaign. This loads your container on every page:
_data/campaigns.json
{
  "my-campaign": {
    "name": "My Campaign",
    "gtm_id": "GTM-XXXXXXX"
  }
}
  1. In assets/config.js, switch gtm on. This makes the campaign send its events to the container:
assets/config.js
// Inside analytics.providers:
gtm: {
  enabled: true
},
  1. Build with npm run build and deploy.

Both parts are needed

With only gtm_id, the container loads but receives no campaign events. With only the config.js setting, the events are sent but there is no container to receive them.

Events you can build tags on

Each event reaches GTM as a data layer event. Create a Custom Event trigger with the event name, then attach your tag.

Event nameWhen it happens
dl_user_dataAny page loads. Use this for page view tags
dl_view_itemA page shows a product
dl_add_to_cartAn item is added to the cart
dl_begin_checkoutThe checkout loads
dl_add_shipping_infoA shipping address is entered
dl_add_payment_infoPayment details are entered
dl_purchaseThe order is paid. Sent on the first page after payment
dl_viewed_upsellAn upsell page is shown
dl_upsell_purchaseAn upsell is accepted. Sent on the page after it

The full list, with every field, is in the SDK's Analytics events reference.

Reading values in your tags

Create Data Layer Variables in GTM for the values you need.

What you wantData layer variable
Order numberecommerce.transaction_id
Amountecommerce.value
Currencyecommerce.currency
Itemsecommerce.items
Shipping and taxecommerce.shipping, ecommerce.tax
UTM parametersattribution.utm_source, attribution.utm_medium, attribution.utm_campaign
Google click IDattribution.gclid
Meta click IDattribution.metadata.fbclid

The events also carry the shopper's email, phone, name and address under user_properties. Decide which tags may read them, and see Privacy and consent.

Purchases and upsells

dl_purchasedl_upsell_purchase
WhenThe first page after paymentThe page after an upsell is accepted
Order IDThe order number, for example 100041The order reference followed by -US1, -US2 and so on
AmountThe price of the items as shown on your store, without shippingThe upsell only
  • A purchase is sent once per order. Reloading the page does not send it again.
  • A tag on dl_purchase alone misses upsell revenue. Add a tag on dl_upsell_purchase if you want it.
  • The amount is the item prices only. Add ecommerce.shipping if your platform should see shipping. On a store that shows prices without tax, add ecommerce.tax as well.

Send each platform one purchase

If a platform is already turned on in your campaign, for example GA4 or TikTok, do not also send it purchases from GTM. See Send each purchase from one place.

To count purchases in Google Ads from GTM, add a Google Ads conversion tag on a dl_purchase trigger. Set its order ID to ecommerce.transaction_id, its value to ecommerce.value and its currency to ecommerce.currency. Add a second tag on dl_upsell_purchase to count upsells.

Do this only if you are not already importing purchases into Google Ads from GA4. See Use GA4 purchases in Google Ads.

Verify it works

  1. Start Preview mode in your GTM container and open your campaign.
  2. You should see dl_user_data first, then the other events as you move through the funnel.
  3. Place an order with a test card. On the next page, dl_purchase appears with the order number.
  4. Accept an upsell. dl_upsell_purchase appears on the page after it.

Troubleshooting

ProblemLikely causeFix
The container does not loadgtm_id is missing or emptyAdd your container ID and rebuild
The container loads but receives no eventsgtm is switched off in assets/config.jsSwitch it on
Tags do not fireThe trigger's event name does not matchCopy the name from GTM Preview
A page view trigger never firesIt listens for dl_page_viewUse dl_user_data

More help is in Test and troubleshoot tracking.

Hand-built campaigns

On a campaign that is not built from a starter template, add your GTM container to every page yourself, then switch gtm on as in step 2. See the Campaign Cart SDK analytics docs.

On this page