Pixels and tracking tags

A pixel is the small script an ad network runs on your site to see what people do after they click: page views, add-to-carts, purchases. Conversion campaigns, website audiences and server-side conversions all point at one. Pozy manages every network's pixel through the same endpoints under /v1/accounts/{accountId}/tracking-tags, and installs it on a connected Shopify, WordPress, Wix or Webflow site with one call, without editing a theme.

This page also covers the other kind of "tracking tag": the parameters an ad adds to its click URL, such as utm_source. Those are set per ad. Jump to Click-URL parameters.

#What each network calls it

accountId in the path is always the ads connection (metaads, tiktokads, googleads, linkedinads, pinterestads, xads, openaiads), never a posting account.

Reddit pixels are created in Reddit Ads Manager and are not managed here. Reddit's server-side events still go through Conversions.

#Set up a pixel end to end

curl "https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags?adAccountId=act_1234567890" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags?adAccountId=act_1234567890", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);
console.log(data.tags);

import os, requests

resp = requests.get(
    "https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"adAccountId": "act_1234567890"},
)
print(resp.json())

curl -X POST https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "adAccountId": "act_1234567890", "name": "Storefront pixel" }'

curl -X POST https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags/1729525464415281/install \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "storeAccountId": "66c3d4e5f6a7b8c9d0e1f2a3" }'

#How installs work per site

On WordPress, Wix and Webflow the tag loads its base code and reports page views. Shopify maps store events to each network's conversion events, so create those events first (next section).

#Conversion events

A tag's conversion events are what a site fires and what campaigns optimize for. Manage them on .../tracking-tags/{tagId}/events: list with GET, create with POST, change with PATCH .../events/{eventId}, retire with DELETE.

The body takes a name and either the network's own type or a neutral siteEvent. siteEvent is the store vocabulary the installs use: page_view, view_content, add_to_cart, search, initiate_checkout, add_payment_info, purchase. Networks that store more also take defaultValue and currency, clickWindowDays and viewWindowDays, urlContains and enabled.

curl -X POST https://api.pozy.ai/v1/accounts/66b2e19d8c3f5a7e9d0b1c2d/tracking-tags/7412345678901234567/events \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Purchase", "siteEvent": "purchase" }'

#What each network supports

An operation a network does not offer returns 501 platform_not_supported, and the message names where to do it instead (usually the network's own ads manager).

PATCH .../tracking-tags/{tagId} takes any of name, enableAutomaticMatching, automaticMatchingFields, firstPartyCookieStatus, enableFirstPartyCookies, dataUseSetting and autoTagging. A field the network does not store returns 400 listing the ones it does.

#Sharing

.../tracking-tags/{tagId}/shared-accounts lists (GET), adds (POST with adAccountId) and removes (DELETE ?adAccountId=) the other ad accounts that can use a tag. On Meta the pixel must belong to a Business Manager; on TikTok it must be a Business Center asset; on LinkedIn the grant is use-only and the tag cannot be left with no ad account.

#Users and partners (Meta)

GET and POST .../tracking-tags/{tagId}/users list people with access and assign one with { userId, tasks }. Tasks are AA_ANALYZE, ADVERTISE, ANALYZE, EDIT and UPLOAD. GET .../partners lists partner businesses, read only.

#Network notes

• Meta. A new pixel accepts server events right away, even before the script is on the site. A pixel created on an ad account outside a Business Manager cannot be shared.
• TikTok. Names are up to 40 characters with no emoji. A connection made before TikTok's pixel permission answers every call with 403; reconnect TikTok Ads.
• Google Ads. Each customer has exactly one Google tag. The "create" call turns conversion tracking on and returns the existing tag if it is already on. Its events are the account's website conversion actions.
• LinkedIn. One Insight Tag per ad account. It has no name, so Pozy shows it as Insight Tag <id>.
• Pinterest. The connected user needs a Business Access role on the ad account. Stats take no time range.
• X. One pixel per ad account. Events X creates with the pixel are hidden and cannot be changed. See X Ads.
• ChatGPT Ads. Creating the pixel also creates its Conversions API key. Some ad accounts need pixel management enabled by their ChatGPT Ads representative (422 feature_not_available). See ChatGPT Ads.

#Click-URL parameters

Click-URL parameters are added to the landing page URL when someone clicks an ad, so your analytics can tell where the visit came from. They live on each ad, not on the pixel.

#Set them at launch

tracking.urlTags on POST /v1/ads/create and POST /v1/ads/boost takes { key, value } pairs. tracking.pixelId sets the pixel the ad measures with.

{
  "tracking": {
    "pixelId": "1729525464415281",
    "urlTags": [
      { "key": "utm_source", "value": "meta" },
      { "key": "utm_campaign", "value": "{{campaign.id}}" },
      { "key": "utm_content", "value": "{{ad.id}}" }
    ]
  }
}

Network macros pass through unescaped so the network expands them at click time; everything else is percent-encoded. Meta's macros look like {{ad.id}} and {{placement}}. ChatGPT Ads uses {campaign_id}, {ad_group_id}, {ad_id} and {oppref}.

#Read or change them later

GET /v1/ads/{adId}/tracking-tags reads what an ad carries and PATCH changes it. What you can set depends on the network:

curl -X PATCH https://api.pozy.ai/v1/ads/66f0a1b2c3d4e5f6a7b8c9d0/tracking-tags \
  -H "Authorization: Bearer $POZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "finalUrlSuffix": "utm_source=google&utm_medium=cpc&utm_campaign={campaignid}" }'

#Errors you will see

#Endpoints