Keitaro Postback Setup: Click ID, Status and Payout Mapping

A Keitaro postback works when the affiliate network returns the exact subid created for the original click and supplies a valid status. Payout, currency and transaction ID make the conversion useful, but subid and status are the mandatory lookup contract.

The shape is:

https://tracker.example/POSTBACK_KEY/postback?subid={NETWORK_CLICK_MACRO}&status={NETWORK_STATUS_MACRO}&payout={NETWORK_PAYOUT_MACRO}&tid={NETWORK_TRANSACTION_MACRO}

Do not paste those generic macro names into production. The parameter keys on the left belong to Keitaro; the placeholders on the right must be replaced with the exact macros documented by the affiliate network.

What Keitaro expects

Keitaro’s current official postback documentation identifies two mandatory incoming parameters:

Keitaro also supports aliases for partners that send different incoming key names. Configure aliases deliberately; do not assume that clickid or profit will be interpreted correctly without that mapping.

Step 1: pass Keitaro subid into the offer

Keitaro creates {subid} when the click enters the campaign. The affiliate network must store that value in one of its available fields.

If the network expects aff_sub:

https://network.example/offer?aff_sub={subid}

If it expects sub1:

https://network.example/offer?sub1={subid}

The field name is network-specific. A ready-made Keitaro affiliate-network template may fill it automatically; otherwise add it to the offer URL and confirm the delivered URL contains a real value rather than literal {subid}.

Step 2: return the stored value to Keitaro

The direction now reverses. Suppose the network stores the click under aff_sub and exposes {aff_sub} as its postback macro:

https://tracker.example/POSTBACK_KEY/postback?subid={aff_sub}&status={status}&payout={payout}&tid={conversion_id}

At runtime it should resolve to something like:

https://tracker.example/POSTBACK_KEY/postback?subid=cb0d82f4a2&status=sale&payout=42.50&tid=conv_98211

The name on the right can be {sub1}, {click_id}, {aff_sub} or something else. Use the network’s documentation. Keitaro only needs the resolved value to match the click it created.

Step 3: map statuses before launch

Keitaro supports base and custom conversion types. A network may send new, reg, approved, deposit, billed, rejected or vertical-specific values.

Write the mapping down before traffic starts:

If a raw value is not a configured type and no status training exists, Keitaro can ignore the callback. A successful HTTP response is not proof that the conversion entered reports.

Step 4: use tid for real repeated conversions

One click can generate registration, first deposit and later deposits. Keitaro documents tid as the transaction identifier used to record repeated conversions separately.

Do not reuse one tid for every event on the click. Do not generate a new random value for a literal retry of the same network transaction. The safe contract is:

• one business conversion → one stable transaction ID;
• the same retry → the same transaction ID;
• another real deposit → another transaction ID.

Step 5: validate the path in the right order

Keitaro’s official troubleshooting guide recommends following this same direction: confirm subid reached the network, then inspect the postback log and conversion type.

Common Keitaro postback errors

Click for subid not found

The network returned an empty, literal or different value. Compare the outbound offer URL with the raw incoming callback byte for byte.

Postback status is not set

The network macro did not expand, the parameter was omitted or an alias was configured incorrectly.

Conversion type not found

The raw status is unknown. Create the intended custom type or configure status training before retrying.

Incorrect postback code

The security key in the callback URL does not match the tracker’s current Postback URL. Copy the endpoint from Keitaro settings rather than reconstructing it from memory.

The same conversion overwrites another one

Add a stable tid when the network can send multiple legitimate conversions with the same status.

Keitaro with a PWA or another routing layer

Every additional redirect creates another place where subid, fbclid, ttclid or campaign fields can disappear. Keep responsibilities explicit:

1. Keitaro owns {subid} and its campaign report.
2. The PWA or routing layer preserves the incoming context.
3. The affiliate network stores the Keitaro click ID.
4. The network returns the conversion to the Keitaro postback URL.
5. Any additional event forwarding happens only after the tracker-side conversion is correct.

Use Click ID vs Sub ID when identifier roles are unclear, the Postback URL Builder to inspect a resolved callback, and postback troubleshooting when the endpoint returns 200 but reports remain empty.

Final acceptance rule

The setup passes only when one controlled click produces one correctly typed conversion on the original Keitaro row with the intended payout—and the identical callback cannot add it twice. Everything earlier is configuration evidence, not the result.