Ad URL tracking tags

Audit or fix the attribution parameters on an ad's click destination with GET and PATCH /v1/ads/{adId}/tracking-tags.

These are Meta's url_tags, the UTM-style query parameters appended to the landing page URL.

They are unrelated to Meta Pixels, which share the path segment but measure events.

Read the parameters

The read works on ads Zernio created and on ads discovered from Ads Manager.

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: tags } = await zernio.trackingtags.getAdTrackingTags({
  path: { adId: '66d4a1b2c3e4f5a6b7c8d9e2' }
});

console.log(tags.urlTags);

Response (200):

{
  "platform": "facebook",
  "level": "creative",
  "urlTags": "utm_source=meta&utm_medium=cpc",
  "templateUrlSpec": null
}

The fields:

• urlTags is the &-joined parameter string.
• templateUrlSpec is Meta's third-party click-tracking template, used by dynamic ads.
• level says which object holds them. On Meta that is the creative.

Set the tags

PATCH takes urlTags as an array of { key, value } pairs.

Meta creatives are immutable, so the update rebuilds the creative and repoints the ad.

Zernio preserves the existing creative verbatim, re-posting its current headline, body, call to action and image. The image is reused by hash rather than re-uploaded, so urlTags is all you send.

await zernio.trackingtags.updateAdTrackingTags({
  path: { adId: '66d4a1b2c3e4f5a6b7c8d9e2' },
  body: {
    urlTags: [
      { key: 'utm_source', value: 'meta' },
      { key: 'utm_medium', value: 'cpc' },
      { key: 'utm_content', value: '{{ad.id}}' }
    ]
  }
});

Response (200):

{
  "platform": "facebook",
  "level": "creative",
  "urlTags": "utm_source=meta&utm_medium=cpc&utm_content={{ad.id}}",
  "templateUrlSpec": null
}

The PATCH answers with the rebuilt creative's tags, so no read-back is needed.

Meta's dynamic macros ({{ad.id}}, {{campaign.id}}, {{placement}} and the rest) go through unescaped so Meta expands them. Every other character is percent-encoded.

The rebuilt creative goes through Meta review again.

creative is optional and takes headline, body, callToAction, linkUrl and imageUrl together. Send it only to rebuild the creative explicitly, or for the creatives Zernio cannot preserve.

Set tags at create time

tracking.urlTags (and tracking.pixelId for pixel measurement) is also accepted on every Meta create flow:

• the POST /v1/ads/create single, multi-creative and attach shapes
• POST /v1/ads/boost
• POST /v1/ads/messaging / POST /v1/ads/ctwa

It lands on the new creative's url_tags, the same place this page's GET reads from. A value set at create now reads back correctly instead of null.

The ad also keeps its own copy for compatibility.

{
  "tracking": {
    "pixelId": "1729525464415281",
    "urlTags": [
      { "key": "utm_source", "value": "meta" },
      { "key": "utm_medium", "value": "cpc" }
    ]
  }
}

If it fails

A 422 means Meta stripped the creative's object_story_spec, so there is nothing to preserve:

{
  "error": "Meta creative cannot be rebuilt; supply creative",
  "type": "invalid_request_error",
  "param": "creative"
}

Send the creative object with all 5 fields. This is what SHARE, page-post boost, dark post and Advantage+ asset-feed creatives return.

A 405 means the ad's platform has no click-URL tracking surface, which covers TikTok, X and Pinterest.

A 502 means Meta accepted the rebuild and then failed to produce the media. Read platformError.reason.

Related

• Pixels: the measurement tags on the same path segment.
• Creatives: the other way to replace a live creative.
• Campaigns: tracking.urlTags sets the same parameters at create time.
• Read tracking tags and Update tracking tags: every field.