Home / Guides

Turning captured dataLayer pushes into a GTM container you can import

What a container export file has to contain, the two fields that make GTM refuse the whole import, and why placeholders beat blanks.

Published 12 August 2026 · By hsynkvlc

You have watched a site push purchase with eight parameters. Now somebody has to create eight Data Layer Variables, a Custom Event trigger and a tag that wires them together — by hand, in a web form, once per event. GTM will accept that as a file instead, and the file is not complicated once you have seen one.

The three pieces

A container export is JSON with an exportFormatVersion, a containerVersion envelope and three arrays inside it: variables, triggers and tags. Account and container IDs can all be 0 — the import screen maps the file onto whichever container you are importing into, so the numbers in the file are placeholders by design.

• A Data Layer Variable per dot path: type v, with dataLayerVersion: 2 and the path as its name. One per unique path, however many events use it — the same ecommerce.value should not become four variables.
• A Custom Event trigger per event: type CUSTOM_EVENT, with a filter that says {{_event}} equals the event name.
• A tag per event, with firingTriggerId pointing at that trigger's ID. IDs are just strings you assign; they only have to be consistent inside the file.

The two fields that make the whole import fail

This is the part worth the price of admission, because the failure is all-or-nothing: GTM refuses the file rather than importing what it can.

A GA4 event tag with an empty measurement ID. The error names the exact path:

• containerVersion.tag[0].vendorTemplate.parameter.measurementIdOverride: The value must not be empty.

There is a trap behind this one. The older model was to point a GA4 event tag at a configuration tag by name, and plenty of guides still describe it that way. That is not what the current template validates against — it wants measurementIdOverride filled in, and an event tag written the old way will not import.

An Ads conversion tag with an empty conversion ID or label. Same behaviour, same all-or-nothing refusal. The template also wants the ID as the bare number — 993214470, not AW-993214470 — and a label of letters and digits only.

Placeholders beat blanks

The instinct when you do not know an ID is to leave it empty rather than invent one. For this file that instinct produces the worst outcome: nothing imports, so there is no tag to go and correct.

A placeholder in the right shape — G-XXXXXXXXXX, 000000000 — imports cleanly and leaves you a tag sitting in the container with an obviously wrong value in one field. That is a two-second fix instead of a rejected file.

Better still is not to guess at all. The IDs are readable from the page you were just on: the measurement ID is the tid on the GA4 hits it sent, and the Ads conversion ID and label are the account and the label parameter on the conversion request. Where a site runs more than one GA4 property, the one sending the most hits is the one you want.

Mapping parameters without thinking about it

Two small rules do most of the work. For a GA4 event tag, the parameter name is whatever follows the last dot in the path, so ecommerce.value becomes a parameter called value. For an Ads conversion, only three fields matter — value, currency and order ID — and matching on the tail of the path means ecommerce.value and a bare value both land in the right box.

Import it, but read the diff

GTM's import has two modes, and the difference is not subtle. Merge adds to what is there; overwrite replaces the workspace with the file, which on a real container is a way to lose a lot of work in one click.

Import into a new workspace, choose merge, and read the preview it shows you before confirming: GTM lists exactly what will be added, changed and deleted. Anything generated deserves that read, including a file generated from your own site's traffic.

What this does not do

It gives you tags that fire on the right events with the right parameters. It does not know your naming convention, your folder structure, your consent settings, or which of these events you actually want sending to production. Treat it as the tedious 80% done for you, not as a finished implementation.

Related guides

• One click, three pushes: picking the right dataLayer event
• How to debug server-side GTM
• Debugging Consent Mode V2: gcs, gcd and the violations nobody catches