Postbacks and conversions

A conversion is a network’s report of an event on one of your clicks. The network reports it with a postback: a request to a URL Tallyray gave you. This guide covers setting up the postback, what Tallyray does with each one, and how conversions reach your traffic source.

A click's path: the ad, your campaign, the lander and the offer. The way back is the network's postback to Tallyray, and the conversion Tallyray sends to the source.

Set up a network’s postback

1. Under Tracking, Networks, add the network on its template. Pick the network’s own template if it has one; otherwise pick Any network (postback URL).
2. Make its postback token. The token (npt_…) is shown once, with the whole URL: https://<your tracking domain>/postback/<token>. Only the workspace’s owner makes it. Until it exists, the network’s postbacks are refused. If you need the URL whole again, make a new token: the old one keeps working for as long as you choose (none, an hour, a day or 7 days) while you update the network.
3. Paste the URL into the network’s postback settings, with the network’s own macros where the click id, payout, status and event go. For a network with its own template, the portal fills them in; for the generic one, the page asks for the network’s macro for each field, to build the URL.
4. In the offer’s URL, {click_id} stands where the network takes the click id: see Campaigns, flows, landers and offers.

Build the URL

Pick the network to see the postback URL its template writes, with the network’s macros in it. This is the URL the portal shows; the token is shown there once, when it is made.

NetworkAdjustAppsFlyerBranchKochavaAny network (postback URL)prismSingular

Your tracking domain

Postback URL

https://trk.example.com/postback/npt_…?cid={label}&et={event_name}&status={activity_kind}&payout={revenue_float}&currency={currency}

Copy

Adjust calls this URL for every conversion and every change to one. Replace npt_… with the token the portal shows, once, when it is made.

The fields a postback carries

Field	Meaning
cid	The click id from your offer’s URL. Required. A click id Tallyray never issued is refused.
et	The event: an event type’s code, or the network’s name for a kind (its template maps it).
status	The network’s status for the conversion, read through the template: approved, pending, declined or chargeback. No status means approved.
payout and currency	The amount, with at most 6 decimals. A postback without a currency uses the network’s currency.
txid	The network’s transaction id, up to 255 bytes.
ts	When it happened, in a signed postback.

Emails, phones and similar identifiers a postback carries are hashed the moment they arrive and are never stored, logged or shown raw.

Who may post

Under the network’s page, Who may post controls:

• Allowed addresses: IPs or CIDR ranges. Empty accepts any address (a pixel, which comes from a visitor’s browser, is exempt).
• Signing: for a network whose template signs its postbacks (prism’s), postbacks must be signed, and Tallyray checks the signature with the secret you enter. A signature more than 5 minutes off Tallyray’s clock is refused. Turning the requirement off needs allowed addresses.

The pixel

A network can also call a pixel, https://<your tracking domain>/pixel/<pixel token>.gif, which takes the click id from a cookie Tallyray sets when the visitor clicks through. It is off until you turn it on for the network, and an unsigned pixel can only make a conversion’s first approval.

What Tallyray does with a postback

1. The edge checks it. A refused postback is answered with a reason: invalid_token, ip_not_allowed, signature_required, invalid_signature, stale_signature, missing_click_id, invalid_click_id, unknown_status, unknown_event, invalid_amount, invalid_currency, invalid_timestamp, pixel_disabled, network_archived, workspace_suspended. All but two are recorded, and you see them under Activity, Postbacks. invalid_token (a token no network has) and invalid_click_id (a click id Tallyray never issued, an old tracker’s included) are answered and never recorded, so nobody can fill your log by guessing: they show nothing anywhere.
2. If it repeats the last thing the network said about the same conversion (same transaction, event, status and payout), it is answered duplicate and nothing changes. Anything else is a change.
3. Attribution matches it to its click. If the click has not reached reports yet, the postback waits: Tallyray tries every 5 seconds for 10 minutes, then with growing waits up to 24 hours. After that it is unprocessable (click_not_found) and listed under Postbacks, waiting, where you can replay it once the cause is fixed.
4. A conversion is made, or an existing one changed. Another postback for the same transaction and event with a new status or amount changes the conversion, however old its click.

A first conversion on a click older than the workspace’s click window (90 days by default; Settings) is kept but unattributed (click_expired).

A workspace that is suspended keeps converting the clicks it took before the suspension, and takes none after.

Conversions

Each conversion has an event type, a status, a revenue and, for CPA and revshare campaigns, a cost.

Statuses

Status	In reports
Approved	its revenue counts as earned; sources’ templates send it by default
Pending	held by the network; its revenue shows apart
Declined	no revenue
Chargeback	approved, then taken back; no revenue

A network’s later postback moves a conversion to any status. You can also change a status by hand under Activity, Conversions: it is made as a postback would be and kept in the conversion’s history, with your note.

Revenue

The revenue is the postback’s payout, or, if the offer’s payout is fixed, the offer’s amount whatever the postback says. A postback with no payout on an offer set to take the postback’s gets the offer’s amount. A changed payout on a later postback adjusts the revenue. A new offer payout prices the conversions made after it.

Event types

Every workspace has a built-in event type for each kind: lead, registration, sale, deposit, subscription, rebill, and an app’s install and reengagement. You can add custom ones under Settings, Event types. An event type has:

• a code (^[a-z0-9][a-z0-9_.-]{0,63}$) and a name, fixed once made;
• repeatable: whether one click may convert on it more than once, each with its own transaction id. Rebills and sales are repeatable by default;
• counted: whether reports count it in their conversions column and caps count it. Every event type is also counted under its own name.

A postback with no event is of the template’s default kind (a sale if it gives none). A duplicate on a click and a non-repeatable event type is the same conversion.

Offer caps

An offer’s daily cap counts approved and pending conversions that day, in the workspace’s time zone. When it is reached, clicks go to the fallback offer, or the offer leaves rotation without one, until the day ends or the cap is raised. Conversions declined or charged back free a place.

Conversions back to your traffic source

For each source, the template says what is sent and how. Tallyray sends one request per change to a conversion that matches the template’s rules, to the connection of the click’s campaign, and only to that one.

• By default only approved conversions go, up to 30 days old for the postback sources (the platforms’ templates differ: see each source’s page). A conversion goes once per status it enters.
• Only the events the template maps go. A buyer can override the events and statuses sent.
• Bots’ conversions are never sent.
• A failed delivery is retried with growing waits. Under Activity, Call log, you see each call made to a source, redacted. Under Deliveries you can send failed ones again, up to 500 at a time, within their age limit.
• Meta, Google Ads and TikTok take a test conversion you send from the connection, with the event and value you choose. Google checks it without recording it; Meta and TikTok need a test event code.
• Personal data goes only where the platform needs it and consent allows: for a visit from the EEA, the UK or Switzerland without consent, the conversion goes without anything personal, or not at all if nothing is left to match on. An explicit denial withholds hashed identifiers wherever the visitor came from.

A conversion made without a click (a coupon or an app’s aggregated postback) is never sent to a source: see Coupons, organic traffic and apps.

Costs

Costs reach reports in four ways: a token the source passes with each visit, a per-visit or per-conversion price on the campaign, spend pulled from the source’s API where its template supports it, and spend you enter by hand. Reports use whichever applies, and a pulled spend slice replaces what the visits’ own costs said for the period it covers. See Reports.

If conversions do not show up

You see	Check
Nothing under Postbacks	the network’s token exists and the URL you pasted is whole (a wrong token is answered invalid_token and never recorded), the click id is one from your offer’s URL (one Tallyray never issued, an old tracker’s included, is never recorded either), and the network is calling the URL
A refusal reason under Postbacks	the reason above names what to fix
Waiting for the click	the click id in the postback is one from your offer’s URL; wait, or replay later
click_expired	the click is older than your click window
A conversion but not at the source	the template maps its event, the status is one it sends, and the call log shows the call