Tokens
Every macro UTMCAP substitutes into an offer or landing page URL, what each one resolves to, and what happens to one it does not recognise.
A token is a placeholder UTMCAP replaces at the moment of the redirect. Write them into an offer URL or a landing page URL and the visitor's own values go out with them.
https://network.example/offer/9?aff_sub={utmcap_id}&geo={country}&dev={device_type}
Every value is URL-encoded on the way out, so a city with a space or a referrer with a query string of its own cannot break the URL it lands in.
Not to be confused with your traffic source's macros, which are the platform's placeholders and arrive on the way in. See traffic sources.
#The click
| Token | Resolves to |
|---|---|
{utmcap_id} |
This click's id — also {click_id}, {clickid}, {cid} |
{timestamp} |
Unix seconds |
{cost} |
What this click cost |
{currency} |
The campaign's currency |
{utmcap_id} is the one that must be in every offer URL. Without it a
conversion cannot be joined back to the click that earned it.
#What it belongs to
| Token | Resolves to |
|---|---|
{campaign_id} {campaign_name} |
The campaign this click belongs to |
{source_id} {source_name} |
The traffic source it was bought from |
{offer_id} {offer_name} |
The offer, empty unless routed to one |
{lander_id} {lander_name} |
The lander, empty unless routed to one |
{payout} |
What the destination pays |
The offer and lander pairs are exclusive: a click being sent to a lander has no offer yet, and the offer tokens resolve to empty rather than to something wrong.
#Who the visitor is
| Token | Resolves to |
|---|---|
{country} {region} {city} |
Where, by IP |
{isp} {asn} {connection_type} |
Whose network |
{device_type} {device_brand} |
Phone, tablet, desktop — and make |
{os} {os_version} |
Operating system, and its version |
{browser} {browser_version} |
Browser, and its version |
{language} |
Their browser's language |
{ip} {user_agent} |
The raw address and browser string |
{referrer} |
Where they came from |
Passing {ip} and {user_agent} on to a network is often required for their
own fraud checks. Both identify a person: send them where you have a reason to,
not by default.
#Whatever came in
| Token | Resolves to |
|---|---|
{sub1} … {sub10} |
The sub slots, as filled by the source's macros |
{query.NAME} |
Any query parameter on the incoming URL, by name |
{query.…} is the escape hatch for a value no slot is holding — a platform
parameter you did not map, or something you appended yourself. {query.gclid}
passes Google's own click id straight through.
#Your source's own names
Each slot also answers to the name your traffic source gives it. If sub3
holds {zone_id} on PropellerAds, then {zone_id} is a token too, and means
the same thing:
https://network.example/offer/9?aff_sub={utmcap_id}&zone={zone_id}
Use these rather than the slot numbers where you can. {sub3} is a storage
location; zone_id is a name. A URL written in slot numbers only makes sense
to someone who remembers which slot held what, on which source.
They are per source. {zone_id} fills in for a click from PropellerAds.
For a click from Google it comes out empty, because Google sends no zone.
{sub1} to {sub10} work on every source — these do not.
To see the names your own sources answer to, open an offer or a landing page, click Tokens glossary under the URL field, and look under each source's name. Clicking one puts it in the URL.
Where a name would clash with one of ours it takes src_ in front. Your
source's campaign is {src_campaign_id}, because {campaign_id} already means
your UTMCAP campaign.
#The platform's own click id
{external_id} is your traffic source's id for the click — PropellerAds'
${SUBID}, Google's {gclid}, Meta's fbclid. It is not {utmcap_id}, which
is ours.
Two places use it:
- The postback back to your traffic source, so the platform learns which of its clicks paid. See traffic sources.
- Your offer URL, when the affiliate network wants it — some do, so their reports line up with the platform's.
https://network.example/offer/9?aff_sub={utmcap_id}&pub_clid={external_id}
Those two are not the same value and should not go in the same parameter.
{utmcap_id} is the one the network must send back. {external_id} is for
their reporting.
It is empty on a source that captures no click id — never our id instead, which would tell the network the platform knows a click by an id it has never seen.
#Random
{random:N} produces N random lowercase letters and digits, up to 32.
For a cache-buster on a network that caches too aggressively, or a unique value a destination requires and nothing else supplies.
#An unknown token
It is replaced with nothing.
Not left as literal text, not an error — removed. So {clickid} works,
{click-id} does not, and the difference between them is a parameter that
silently arrives empty.
That is worth knowing because it fails in the quietest possible way: the redirect works, the visitor reaches the offer, the network records the conversion against an empty sub-id, and nothing attributes. If a network says your click ids are blank, a misspelled token is the first thing to check — against the table above, character by character.
The same applies to a token that is spelled correctly but empty for this
visitor: {city} on an IP the geo database cannot place resolves to empty, and
the parameter arrives blank rather than absent.
Tracking tips by email
Practical tips on tracking, attribution and ad costs, from the people who build UTMCAP.
Unsubscribe any time. Privacy policy