Google Tag Manager

Manage tags, triggers, and variables in Google Tag Manager containers directly from Zeotap. Use warehouse data to programmatically create and update GTM resources via the Tag Manager API v2.

Prerequisites

A Google Tag Manager account with at least one container
Edit access to the container you want to manage
The Tag Manager API enabled in your Google Cloud project
Your GTM Account ID and Container ID

Permissions

To use this integration, your Google account must have one of the following GTM roles:

Container Edit — required for creating and updating tags, triggers, and variables
Container Publish — required if you also need to publish changes after syncing

Authentication

Google Tag Manager uses Google OAuth 2.0 for authentication.

In Zeotap, navigate to Destinations and click Add Destination
Select Google Tag Manager
Click Connect with Google
Sign in with a Google account that has edit access to your GTM container
Grant Zeotap permission to manage your Tag Manager containers
You will be redirected back to Zeotap after authorization

The OAuth scope requested is tagmanager.edit.containers, which allows Zeotap to create, read, and update tags, triggers, and variables in your containers.

Configuration

Field	Type	Required	Description
Account ID	Text	Yes	The GTM account ID. Find this in Tag Manager under Admin > Account Settings.
Container ID	Text	Yes	The GTM container ID. Find this in Tag Manager under Admin > Container Settings.
Workspace ID	Text	No	The workspace ID to write resources into. If left blank, Zeotap uses the default workspace.

Finding Your Account and Container IDs

Open Google Tag Manager
The Account ID is the numeric value shown under Admin > Account Settings
The Container ID is the numeric value shown under Admin > Container Settings (not the GTM-XXXXXX public ID)
The Workspace ID is visible in the URL when you open a workspace: ...workspaces/{workspaceId}

Target Settings

Field	Type	Required	Description
Resource Type	Select	Yes	The type of GTM resource to create or update: Tag, Trigger, or Variable

Supported Operations

Sync Modes

Mode	Supported	Description
Insert	Yes	Creates new GTM resources. Fails if a resource with the same name already exists.
Upsert	Yes	Creates new resources or updates existing ones matched by name.
Update	—
Mirror	—

Audience Sync Modes

Google Tag Manager does not support audience sync modes. GTM is a tag configuration management platform, not an audience or membership system.

Features

Field Mapping: Yes — Map warehouse columns to GTM resource fields
Schema Introspection: No

Required Mapping Fields

Field	Description
`name`	The name of the GTM resource (tag, trigger, or variable)
`type`	The GTM resource type identifier (e.g., `ua` for Universal Analytics tag, `awct` for Google Ads conversion tag, `PAGEVIEW` for pageview trigger, `jsm` for custom JavaScript variable)

Default Destination Fields

Field	Type	Description
`name`	string	The display name for the GTM resource
`type`	string	The GTM resource type identifier
`parameter_key`	string	A parameter key for the resource configuration
`parameter_value`	string	The value for the parameter key
`firing_trigger_id`	string	The trigger ID that fires this tag (tags only)
`notes`	string	Optional notes or description for the resource

How It Works

Workspace Resolution — Zeotap resolves the target workspace. If no workspace ID is configured, it uses the default workspace in the container.
Resource Processing — Each row in your model represents one GTM resource (tag, trigger, or variable). Rows are processed individually because the GTM API does not support batch creation.
Upsert Logic — In upsert mode, Zeotap first searches for an existing resource with the same name in the workspace. If found, it updates the resource using the GTM API PUT method with optimistic concurrency (fingerprint). If not found, it creates a new resource.
Insert Logic — In insert mode, Zeotap creates new resources directly. The API returns an error if a resource with the same name already exists.
API Interaction — Zeotap communicates with the Google Tag Manager API v2, creating or updating resources within the specified account, container, and workspace.

Rate Limits

The Google Tag Manager API enforces strict rate limits:

Limit	Value
Requests per project per day	10,000
Queries per second (QPS)	0.25 (25 requests per 100 seconds)

Zeotap automatically retries failed requests with backoff. Due to the low QPS limit, large syncs with many resources may take longer to complete.

Best Practices

Use upsert mode to avoid duplicate resources when re-running syncs
Keep batch sizes small — the GTM API rate limit of 0.25 QPS means each resource takes approximately 4 seconds to process
Test in a separate workspace before syncing to your production workspace
Publish changes manually — Zeotap creates resources in the workspace but does not publish them automatically. Review changes in the GTM UI before publishing.
Use meaningful names — the name field is used as the lookup key for upsert operations
Map the type field carefully — use the correct GTM type identifier for your resource (see GTM tag type reference )

Troubleshooting

Authentication failed: invalid or expired token

Your OAuth token may have expired. Reconnect the destination in Zeotap by clicking Reconnect on the destination settings page.

Access denied (403 error)

Ensure that:

The Tag Manager API is enabled in your Google Cloud project
Your Google account has Edit access to the container
You authorized the correct Google account during OAuth setup

Container not found (404 error)

Verify that the Account ID and Container ID are correct. These are numeric IDs, not the GTM-XXXXXX container public ID. Find them under Admin > Account Settings and Admin > Container Settings in the GTM UI.

Workspace not found

If you specified a workspace ID, verify it exists in the container. Open the workspace in GTM and check the URL for the numeric workspace ID. Alternatively, leave the workspace ID blank to use the default workspace.

Rate limit exceeded (429 error)

The GTM API allows only 0.25 QPS (25 requests per 100 seconds). Zeotap retries rate-limited requests automatically, but very large syncs may experience delays. Consider:

Reducing the number of resources per sync
Scheduling syncs during off-peak hours
Requesting a quota increase from Google

Resource creation fails with conflict

In insert mode, the API returns an error if a resource with the same name already exists. Switch to upsert mode to update existing resources instead of failing.

Changes not visible in GTM

Resources are created in the configured workspace but are not published automatically. Open the workspace in Google Tag Manager, review the changes, and click Submit to publish them to your container.