How Macros Work
You write the token; the platform replaces it. A campaign URL containing {click_id} is stored with the token intact, and each visitor is redirected to a version with their own value substituted.
https://advertiser.com/offer?cid={click_id}&geo={country}&src={sub_aff1}https://advertiser.com/offer?cid=a7f3c9e1b204&geo=US&src=newsletterYou do not have to type them. The All Macros panel on the campaign form lists every token with its description and inserts it at your cursor, and Quick Tokens below the URL field covers the common ones.
Core Identifiers
The tokens that identify what happened and who is involved.
| Macro | Substituted with |
|---|---|
{click_id} | Unique ID of the recorded click. The key the advertiser returns on the postback. |
{campaign_id} | Campaign reference ID. |
{campaign_name} | Campaign name. |
{affiliate_id} | Affiliate reference ID. |
{advertiser_id} | Advertiser ID. |
{source} | Publisher source label. |
{creativeid} | Creative ID, for per-asset performance. |
{timestamp} | UTC timestamp of the click event. |
{click_id} is the one that cannot be omittedIt is the only value that ties a conversion back to a specific click, affiliate and payout. A campaign URL without it will record clicks and never attribute a conversion.
Visitor and Device
| Macro | Substituted with |
|---|---|
{country} | Country code resolved from the visitor IP. |
{region} | State or region name. |
{ip} | Visitor IP address. |
{os} | Operating system. |
{os_version} | OS version — for iOS 14, this is 14. |
{user_agent} | Full browser user agent string. |
Passing {ip} or {user_agent} to a third party may need a lawful basis and a processing agreement under GDPR and similar regimes. Only forward them where the advertiser has a documented reason — fraud checks, usually — and where your privacy notice covers it.
Affiliate Sub-IDs
Ten free-form slots the affiliate fills at click time, plus their own click identifier. These are the dimensions affiliates optimise on, and each becomes a filterable column in the Clicks Report.
| Macro | Substituted with |
|---|---|
{aff_click_id} | The affiliate's own click ID, used for their postback reconciliation. |
{sub_aff1} – {sub_aff10} | Ten affiliate sub-ID slots. |
Reports only compare across campaigns if sub_aff1 means the same thing everywhere. A common convention is source, creative, placement, ad set, then variant.
Mobile Advertising IDs
Required for app install attribution and for matching against an MMP's own records.
| Macro | Substituted with |
|---|---|
{gaid} | Google Advertising ID (Android). |
{iosidfa} | iOS IDFA. |
{androidid} | Android ID. |
{deviceid} | Generic device identifier. |
On iOS the IDFA is only available when the user has granted App Tracking Transparency permission, so expect it to be empty far more often than not. See Probabilistic Attribution for how installs are matched when no device ID is present.
Platform Click IDs
Ad platform click identifiers. Capture these on the click if you intend to send conversions back to the ad platform through a Conversions API — without the click ID, the platform cannot match your conversion to its own ad spend.
| Macro | Platform |
|---|---|
{fbclid} | Meta (Facebook and Instagram) |
{gclid} | Google Ads |
{dclid} | Google Display |
{gbraid}, {wbraid} | Google, iOS app and web-to-app journeys |
{ttclid} | TikTok |
{msclkid} | Microsoft and Bing |
Postback-Only Tokens
These are populated by the advertiser on the conversion postback rather than at click time. They appear in affiliate postbacks so you can forward conversion detail on to your partners.
| Macro | Substituted with |
|---|---|
{transaction_id} | Unique per conversion. Used for deduplication. |
{order_id} | The advertiser's order or action reference. |
{status} | Conversion status returned by the advertiser. |
{sub_adv1} – {sub_adv6} | Six advertiser-side pass-through slots. |
transaction_id or order_id on every postbackAdvertisers retry postbacks. Without a unique reference, a retry is indistinguishable from a second genuine sale, and you will pay an affiliate twice for one order.
Where to Use Them
| Location | Typical tokens |
|---|---|
| Campaign URL | {click_id} always, plus {country}, {sub_aff1} and any device ID the advertiser needs. |
| Landing page URLs | The same tokens. They are not inherited from the campaign URL. |
| Affiliate postback | {aff_click_id}, {payout}, {status}, {transaction_id}. |
| Impression URL | {campaign_id}, {affiliate_id}, {creativeid}. |
Common Mistakes
| Mistake | Result |
|---|---|
| Square brackets or percent signs instead of curly braces | The token is passed through literally and the advertiser receives the text, not a value. |
| A typo in the token name | Silently substituted as empty. Nothing errors — the parameter simply arrives blank. |
| Tokens on the campaign URL but not on landing pages | Traffic routed to a landing page loses attribution entirely. |
Not URL-encoding values that may contain & or spaces | The advertiser's parameter parsing breaks at the first unescaped separator. |
Assuming the advertiser reads click_id | Every platform names it differently. Confirm which parameter they expect before launch. |
The Link Tester shows the fully substituted URL for a simulated click, which is the fastest way to catch all of the above before real traffic does.