Skip to main content

UTM Mapping

UTM Mapping tells Sealmetrics: "when you see this parameter in the URL, treat it as if it were this standard UTM."

If your team uses custom names like campaign_id, source_id, medium_id or anything else specific to your CRM, ESP or ad platform, UTM Mapping lets you feed those values into Sealmetrics's attribution without having to change how your links are tagged. The visit is classified — including channel grouping, campaign reporting, and source/medium breakdowns — as if the URL had used the standard UTMs directly.

When to use it​

Turn to UTM Mapping when any of the following is true for your setup:

  • Your marketing tool (an ESP, an ad platform, an in-house CRM) emits its own parameter names — e.g. ?campaign_id=summer-sale — and you don't want to (or can't) rewrite every link to use ?utm_campaign=….
  • You've inherited a legacy naming convention that predates GA4 UTMs and rewriting all links is not realistic.
  • A specific vendor appends its own parameter automatically (many affiliate networks, some CMSes) and you want that captured as attribution data.

If your links already carry proper utm_source / utm_medium / utm_campaign, you don't need UTM Mapping.

Where to find it​

  1. Open Settings in the left sidebar (under Site Config).
  2. Go to the UTM Mappings tab.

You'll see:

  • A small form to add a mapping (custom parameter name + target UTM), with an optional Override the UTM if the URL already has one checkbox.
  • A list of the mappings currently active for this site, each with an Override switch.
  • A blue-highlighted note: "Mappings take effect within ~5 minutes and apply to future traffic only."

How it works​

For every visit that comes in, Sealmetrics parses the URL query string and then applies your mappings before classifying the visit. Concretely: if you have a mapping campaign_id → utm_campaign and a visit arrives with ?campaign_id=black-friday, the pixel treats the visit as if it had ?utm_campaign=black-friday — including for channel grouping, source/medium reports, and everything downstream.

The mapping runs at ingest time. It doesn't rewrite the URL your visitor saw; it just enriches the internal representation Sealmetrics uses for attribution.

The rules​

Five rules define exactly what happens, and they're worth internalizing:

  1. Explicit UTMs win by default. If the URL already carries a non-empty value for the target UTM, the mapping is skipped: a mapping never overwrites a value your team put in explicitly. Example: with campaign_id → utm_campaign, a URL like ?campaign_id=X&utm_campaign=Y classifies with utm_campaign=Y. The explicit Y wins.

    Unless you enable "Override the UTM if the URL already has one" on that mapping. With that option on, the mapped value is applied even when the URL already carries the target UTM — in the example above, the visit would classify with utm_campaign=X. Use it when the UTM in the URL is not yours to control: most often a Google Shopping or Performance Max product feed, whose links already arrive with utm_source, utm_medium and utm_campaign set by the platform, and where the Google Ads final URL suffix can only append parameters, never remove them (see use case 4). The option is set per mapping and is off by default — mappings you created before it existed keep behaving exactly as they did.

  2. Copy, not move. The custom parameter isn't removed from the URL — it's copied into the target UTM. Both values coexist internally. This matters for custom properties or downstream logic that might still look at the original param.

  3. Empty or missing = no-op. If the custom parameter is absent from the URL or its value is empty (?campaign_id=), the mapping does nothing. Empty values never "clear" a UTM.

  4. Self-mappings are ignored. A mapping like utm_source → utm_source is silently skipped — it has no meaningful effect.

  5. First-created wins on ties. If you configure two custom parameters mapping to the same UTM (e.g. campaign_id → utm_campaign and campaign_code → utm_campaign), and a visit carries both, the mapping created earlier wins. The evaluation order is deterministic across every visit — you'll never see one visit resolve one way and another visit resolve differently.

    The exception is the override option: a mapping with Override the UTM if the URL already has one enabled writes unconditionally, so it also replaces what an earlier mapping wrote on the same UTM. If several overriding mappings target the same UTM, the most recently created one wins.

Put together, for any one target UTM the final value is decided like this:

The URL carries…Mapping without overrideMapping with override
No value for the target UTMMapped value is appliedMapped value is applied
A non-empty value for the target UTMURL value is kept, mapping skippedMapped value replaces the URL value
The custom parameter empty or absentNothing happensNothing happens — override never clears a UTM

How fast do changes take effect?​

Roughly 5 minutes after adding or removing a mapping, for new traffic. That's the interval at which the pixel refreshes its per-account cache.

Changes are not retroactive. Visits that came in before your mapping was live keep whatever UTMs they had at ingest. UTM Mapping is a forward-looking configuration, not a data migration.

Adding a mapping​

In the UTM Mappings tab:

  1. Type the custom parameter name exactly as it appears in your URLs (case-sensitive: Campaign_ID and campaign_id are different). Do not include the ? or =.
  2. Pick the target UTM from the dropdown:
    • Source (utm_source)
    • Medium (utm_medium)
    • Campaign (utm_campaign)
    • Term (utm_term)
    • Content (utm_content)
  3. Optionally tick Override the UTM if the URL already has one. Leave it unticked unless the URL's own UTMs are outside your control (see rule 1). You can also toggle it later, per mapping, from the list.
  4. Click Add. The mapping is active within ~5 min.

You can only map to one of those five standard UTMs. Sealmetrics doesn't let you invent new attribution fields via UTM Mapping — for grouping the values into custom channels, use Channel Grouping instead.

Each custom parameter name can only map to one target UTM per site (attempting to add a second mapping for the same custom name is prevented by the API).

Turning the override on or off later​

Each row in the mappings list has an Override switch. Flipping it changes only that mapping, and — like every other change here — takes effect for new traffic within ~5 minutes and is not retroactive: visits already classified keep the UTMs they got at ingest.

Removing a mapping​

Click Remove next to the mapping you want to delete and confirm. As with any change, effective in ~5 min, non-retroactive. Historical visits classified through that mapping keep their existing UTMs.

How UTM Mapping interacts with Channel Grouping​

UTM Mapping and Channel Grouping are two features that compose. Understanding the order matters:

URL arrives  →  UTMs extracted  →  Your UTM Mappings applied
             →  Channel rules evaluated (custom → default)
             →  Channel assigned to the visit

The mapping runs first. By the time your channel rules see the visit, the mapped UTMs look identical to explicit ones. This means:

  • Your channel rules can (and should) be written against the standard UTM values, never against your custom parameter names. Once mapping is in place, you never need to reference campaign_id in a channel-grouping rule — you write the rule against utm_campaign and it just works.
  • Deleting a UTM Mapping while relying on it in a channel rule will "un-classify" future traffic: the channel rule keeps looking at utm_campaign, but nothing populates it anymore. Test in the Test a visit tester before removing a mapping.

Common use cases​

Use case 1 — ESP with its own naming convention​

Your email service provider tags every link as ?email_campaign=…&email_source=…&email_content=…. You want that traffic to appear as Email in your Channels report and to break down properly by campaign and creative.

Mappings to add:

Custom parameterMaps to
email_campaignCampaign (utm_campaign)
email_sourceSource (utm_source)
email_contentContent (utm_content)

Once live, an email link like ?email_source=mailchimp&email_campaign=black-friday-2026&email_content=cta-top classifies as Email (the medium default catches Mailchimp) with the campaign and content populated.

Use case 2 — Ad platform with a proprietary click ID as source​

Your ad platform appends ?ad_source=my_platform&ad_medium=display on every click. You want to see it as its own channel.

Mappings:

Custom parameterMaps to
ad_sourceSource (utm_source)
ad_mediumMedium (utm_medium)

If my_platform / display doesn't fall into any built-in channel, you can then create a custom channel rule matching source=^my_platform$ under Channel Grouping.

Use case 3 — Legacy campaign_id from a migrated CMS​

You migrated from an older platform that tagged links as ?campaign_id=… and there's too much historical marketing content to rewrite.

Custom parameterMaps to
campaign_idCampaign (utm_campaign)

New links can start using utm_campaign directly — since explicit UTMs win by default (leave the override off on this mapping), both formats coexist safely during the transition.

Use case 4 — Google Shopping / Performance Max product feed​

Your product feed reaches Google with its own tagging — for example utm_source=google, utm_medium=product_sync, utm_campaign=sag_organic — and you add your own parameters through the Google Ads final URL suffix, which can only append parameters, never remove the ones already in the link. Every paid click therefore carries both sets, and by default the feed's values win, so paid Shopping clicks get attributed to the feed's campaign instead of the real one — and there is nothing you can change on the Google Ads side to prevent it.

Put your own values in custom parameters in the final URL suffix (for example sm_source=google&sm_medium=shopping&sm_campaign={campaignid}) and add these mappings, each with the override enabled:

Custom parameterMaps toOverride
sm_sourceSource (utm_source)✅
sm_mediumMedium (utm_medium)✅
sm_campaignCampaign (utm_campaign)✅

With the override enabled on these three mappings, a click arriving as

?utm_source=google&utm_medium=product_sync&utm_campaign=sag_organic&sm_source=google&sm_medium=shopping&sm_campaign=23776388097

is classified as source=google, medium=shopping, campaign=23776388097 — the real campaign. Without the override, the same click would have been classified as medium=product_sync, campaign=sag_organic.

This changes which channel the traffic falls into

Once the medium is shopping instead of the feed's value, these visits are picked up by the Paid Shopping default channel rule (source google or bing with a shopping medium). If you had a custom channel rule catching the feed's tagging (for example matching medium=^product_sync$), review it — it will stop matching the paid clicks. Check a sample URL in the Test a visit tester under Channel Grouping before and after.

Organic product listings from the same feed carry no final URL suffix, so no sm_* parameters arrive and the mappings do nothing: those visits keep the feed's own UTMs (rule 3, empty or missing = no-op).

Limitations​

  • The target must be one of the 5 standard UTMs. You can't map to arbitrary field names via UTM Mapping. For business-specific grouping (Brand vs Non-Brand, per-partner affiliate channels…), see Channel Grouping.
  • No value transformation. UTM Mapping is a rename, not a rewrite: it copies the value as-is. If you need to normalize values (e.g. lowercase them, map fb to facebook), do it at the campaign-tagging step or use Channel Grouping to bucket the raw values into a canonical channel.
  • Case-sensitive on the custom parameter name. Campaign_ID and campaign_id are different parameters. Match your team's actual tagging.
  • Not editable via MCP. UTM Mapping is configured only from the dashboard UI — there are no MCP tools for it.
  • Not retroactive. Only future traffic uses the mapping.
  • The override option never applies to click ID parameters. gclid, fbclid, msclkid and the rest cannot be mapped to a UTM at all, with or without the override.
Written and maintained by the Sealmetrics Team