Skip to content
Browse documentation

Postback macros and hashing modifiers

Every placeholder available in outgoing postback URLs, bodies and HTML snippets, how values are encoded, and {name>SHA256} hashing.

Last updated 4 min read

On this page

Macros are placeholders in curly braces that TrackCrown replaces when a partner postback fires. Names are case-insensitive ({Payout} = {payout}). Unknown macros are left in place unchanged, so another platform's own placeholders survive — and a misspelt macro is sent literally (the postback form warns about it).

Click macros#

Values come from the conversion's click. For a conversion without click they are empty.

MacroValue
{click_id}, {transaction_id}Click ID (32 hex characters)
{offer_id}, {offer_code}, {offer_name}The offer
{aff_id}, {affiliate_id}, {aff_code}The partner
{advertiser_id}The advertiser (empty in partner-created postbacks)
{sub1} … {sub10}Sub IDs of the click
{source_id}Source ID of the click
{gclid}, {fbclid}Ad-platform click IDs of the click (for a conversion without click: the gclid it was reported with)
{country}, {region}, {city}Geo of the click (country as ISO-2)
{device}, {os}, {browser}From the click's user agent
{ip}, {user_agent}The visitor's IP address and user agent
{ext_campaign_id}, {ext_adgroup_id}, {ext_ad_id}, {ext_keyword}Ad-platform campaign, ad group, ad and keyword
{timestamp}Conversion time, Unix seconds
{date}Conversion date in UTC, YYYY-MM-DD
{random}A random value (16 hex characters)

Conversion macros#

MacroValue
{conversion_id}Conversion UUID — the safest de-duplication key for the partner
{event}, {event_name}Event code and name
{payout}Partner payout, 2–4 decimals (6.00, 0.0125)
{revenue}Revenue (empty in partner-created postbacks)
{sale_amount}Sale amount reported by the advertiser
{currency}Currency code of the amounts
{status}approved, pending or rejected
{status_reason}The status reason (hold, postback_reversal, …)
{adv_txid}The advertiser's order ID (txid)
{conversion_ts}, {click_ts}Conversion and click time, Unix seconds
{adv1} … {adv5}Values the advertiser sent
{coupon_code}Coupon code of the conversion
{email}The buyer e-mail sent on the postback — use it hashed, {email>LC_SHA256}

Reversal-only macros#

Filled only in postbacks whose Fire on is Reversals; empty elsewhere.

MacroValue
{old_status}Status before the reversal
{old_payout}, {old_revenue}, {old_sale_amount}Amounts before the reversal ({old_revenue} empty for partner-created postbacks)
{payout_delta}New settled payout minus old (settled = payout if approved, else 0), e.g. -6.00

Hashing modifiers#

Append >MODIFIER inside the braces to send a digest instead of the value — typically for e-mail addresses that ad platforms match on:

ModifierResult
{email>SHA256}SHA-256 hex digest of the value as is
{email>LC_SHA256}Trim and lower-case, then SHA-256 (what ad platforms expect for e-mails)
{x>MD5}, {x>LC_MD5}MD5 hex digest
{x>SHA1}, {x>LC_SHA1}SHA-1 hex digest
{x>LC}Trimmed, lower-cased value

Modifiers work on any macro and are case-insensitive. An empty value stays empty (never the digest of an empty string). An unknown modifier leaves the whole placeholder unchanged.

URL
https://ads.example.com/conv?cid={sub1}&em={email>LC_SHA256}&value={sale_amount}&cur={currency}

Encoding#

WhereEscaping
URL (S2S, image pixel)Every byte except A–Z a–z 0–9 - _ . ~ is percent-encoded (UTF-8). A sub ID containing & cannot break the URL.
POST body starting with { or [JSON string escaping — write the quotes yourself: "payout":"{payout}"
Any other POST bodyForm encoding (space → +)
HTML snippetPercent-encoded like a URL, so values cannot break out of an attribute

Put macros only where a value belongs — not in the host name (the form refuses that).

Postbacks queued after the original request#

When a postback fires later than the original conversion request, it is built from the stored conversion and its click, with the same macros as at ingest:

Fired byValues
End of a hold periodEvery macro. {ip}, {user_agent} and the other click fields are loaded from the click; {email} is empty (no request carries it). If the click store is briefly unavailable the release waits and retries, for up to one hour after the hold ends, then fires with the values stored on the conversion ({ip} and {user_agent} empty).
Reversal or status-update postback from the advertiserEvery macro, {ip} and {user_agent} from the click. {email} is the address sent on that request, else empty.
Approval, rejection or status change in the panel, by API, by CSV import or in the advertiser portalEvery macro: {sub6} … {sub10}, {ip} and {user_agent} are looked up from the click; {coupon_code}, {status_reason} and, for reversals, the reversal-only macros are filled. {email} is empty.
Third-party fraud scoring rejecting a conversionLike a reversal postback; {email} is empty.

Hashing modifiers compute real digests in every case, including Send test from the panel.

Examples#

Partner tracker with its click ID in sub1:

URL
https://tracker.partner.example/postback?clickid={sub1}&payout={payout}&event={event}&tx={conversion_id}&status={status}

JSON POST to your own data warehouse (workspace-wide postback):

JSON
{"conversion":"{conversion_id}","offer":"{offer_code}","partner":"{aff_code}","revenue":"{revenue}","payout":"{payout}","country":"{country}","at":"{conversion_ts}"}

Reversal postback:

URL
https://tracker.partner.example/refund?tx={conversion_id}&was={old_status}&delta={payout_delta}

Destination-URL macros (click macros in offer URLs and transparent links) are described with tracking links.

Something unclear or missing in this article?Tell us