Postback

Postback is a feedback mechanism in online marketing. The term refers to an HTTP request sent from the advertiser's server (affiliate network or own website) to the tracker server to report that a conversion has occurred.

In marketing, a postback is used to transmit information about user actions on a website, such as purchasing a product, registering, or performing another target action.

To record a conversion in statistics, the tracker uses the click ID subid and the conversion status status — these are mandatory postback parameters.

Postback Methods

Conversions are sent to the tracker in the following ways:

1. By an affiliate network or direct advertiser.

2. Using tracker scripts — (KClient PHP and Tracking script) — from sites on third-party hosting when traffic goes directly to your own domain, without involving an affiliate network.

3. Using JS-Adapter — from local sites added to the tracker as archives or from redirect sites. This method is suitable for your own website, not for an affiliate network.

Postback Processing

The tracker receives a postback, finds the click using the subid, and checks the status parameter. If the data is valid, the conversion is recorded in the statistics. If status is missing or the status is unknown without status training, the request is ignored.

Getting the Tracker Postback URL

The Postback URL is the link where the advertiser, affiliate network, or website sends conversion data to the tracker.

Instructions for obtaining the Postback URL for an affiliate network are described in Affiliate Network Postback.

The URL contains:

• Tracker server address
• Postback key — a unique identifier for security and request authentication
• Conversion parameters

To get the Postback URL:

1. Open Settings → Postback URL.

2. Copy the Postback URL.

3. Add any required parameters from the Postback Parameters section if needed.

Additional Postback Parameter Names

In Postback URL → Parameters, you can configure additional names for Postback parameters.

This setup is useful when the affiliate network sends the click ID or other data under names different from the standard subid, status, payout, tid, date.

For example, the tracker will handle both URLs correctly:

http://IP/postback-key/postback?subid=REPLACE&status=REPLACE&payout=REPLACE

http://IP/postback-key/postback?clickid=REPLACE&type=REPLACE&profit=REPLACE

To ensure proper processing, specify the alternative parameter names in the Alias column.

Postback Parameters

Mandatory Parameters

• subid. Click ID in the tracker. The tracker uses this parameter to determine which click the conversion must be attributed to.
• status. Conversion status. The list of basic statuses is specified in Conversion Types section.

Without subid and status, the tracker cannot correctly process the postback.

Optional Parameters

• tid. Transaction ID. Used to record repeated conversions without overwriting the previous one.
• payout. Conversion payout. Positive and negative values are supported.
• cost. Conversion cost for CPA and RevShare cost models.
• currency. Payout currency, for example, usd, eur, rub.
• sub_id_1 - sub_id_30. Additional parameters for updating click data. Supports string and numeric values.
• return. Response text returned to the sender. For example, &return=OK returns OK if the postback is processed successfully.

WARNING

Parameters keyword, cost, external_id, creative_id, ad_campaign_id, and source can also be sent, but the values received will overwrite data previously recorded with the click from the traffic source.

TIP

When sending a postback again with the same subid but different parameters, the tracker will overwrite the previous conversion.

If all postback parameters match the previous conversion exactly, the postback will be processed, but the S2S postback will not be sent again.

Conversion Types

Keitaro supports the following conversion types and displays them in reports:

• Lead — a lead. Payout is not confirmed. Revenue is shown in the Revenue (hold) metric.
• Sale — a sale. Payout is confirmed. Revenue is shown in the Revenue (confirmed) metric.
• Rejected — conversion rejection. Payout is canceled. Revenue is shown in the Revenue (rejected) metric.
• Registration — registration. Revenue is shown in the Revenue (registration) metric.
• Deposit — deposit. Revenue is shown in the Revenue (deposits) metric.
• Trash — irrelevant conversion. Revenue is shown in the Revenue (trash) metric.
• Custom conversion types — additional conversion types for more accurate campaign analytics.

When a Postback is Ignored

• If the status parameter is missing, the tracker ignores the postback and logs the event.

• If a status is sent that is not supported by the tracker and no training is configured, the tracker ignores the postback and logs the event.

Training Non-Standard Statuses

If the affiliate network sends status values that do not match the tracker's base statuses, use special parameters to train the tracker.

The tracker accepts any value in the status parameter and maps it to the appropriate conversion type when training is correctly configured.

Training parameters:

• lead_status
• sale_status
• rejected_status
• registration_status
• deposit_status
• trash_status
• custom*_status — replace custom* with the parameter of a created custom conversion type.

Example

The affiliate network sends registrations with statuses new and registered.

To record these conversions as Registration, add the following training to the postback URL:

status=new&registration_status=new,registered&sale_status=billed&rejected_status=canceled,fake

When a conversion with status=new or status=registered is received, the tracker will map it to the Registration conversion type according to the training specified in the URL: status=new&registration_status=new,registered.

The original status sent by the affiliate network is stored in the Status column in the conversion log.

Recording additional conversions

If two postbacks with the same status are sent sequentially to the tracker, the previously recorded conversion is overwritten by the new one.

To record a conversion as a separate entry rather than overwriting the existing one, send a unique value in the tid parameter in the postback URL.

For example, when sending two postbacks sequentially with the following parameters:

status=sale
status=sale&tid=2

Keitaro will record two separate conversions with the Sale conversion type instead of overwriting the first one.

Convert currency

The tracker stores statistics in a single currency set in Settings → General → Currency.

To convert the payout amount, specify the currency in the Postback URL using the currency parameter. Upon receiving the postback, the tracker converts the payout to the currency set in the tracker settings.

https://example.com/key/postback?status=lead&payout=10&currency=EUR

The tracker-level currency is applied to all campaigns and used for all statistics.

Sending Postback Using Postback Pixel

Postback Pixel is a snippet of code embedded on a page that sends conversion data to the tracker after a target action.

This method is suitable for custom client-side code when the conversion is sent from the page itself rather than from an affiliate network.

1. Use a local landing page, a local offer or a preload page. For details on landing and offer requirements, see the Landing page:Local page.

2. Insert the Postback Pixel code between <body>...</body> on index.html or index.php:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

Replace POSTBACK_URL with the URL from Settings → Postback URL.

WARNING

The {subid} placeholder in the postback URL works only on index.html or index.php.

1. Create an offer or landing page with redirect. Pass subid={subid} in the URL parameters:

2. Insert the Postback Pixel code between <body>...</body> on the page and process the {subid} value passed in the subid= parameter of the URL:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

Example {subid} handler with the pixel:

<script>
        document.addEventListener('DOMContentLoaded', () => {
            const urlParams = new URLSearchParams(window.location.search);
            const subid = urlParams.get('subid');
            const postbackUrl = `POSTBACK_URL?subid=${subid}&status=lead&payout=10&currency=usd`;
            document.getElementById('postback-pixel').src = postbackUrl;
        });
</script>

<img id="postback-pixel" src="" width="1" height="1" />

Replace POSTBACK_URL with the URL from Settings → Postback URL.

Postback FAQ

Why don’t conversions appear?

See Postback Troubleshooting.

How does Keitaro convert currency?

Keitaro requests exchange rates from an external service twice daily.

Why doesn’t a test postback from an affiliate network work?

Affiliate networks do not send a real subid in test postbacks.

To test postback setup, perform a conversion via the tracker campaign link and wait for a real postback.

How to change the Postback key?

The Postback key is a unique string that protects the tracker from fake postback requests.

To replace the Postback key, specify a new value in /etc/keitaro/env/inventory.env:

TRACKER_POSTBACK_KEY=CUSTOM_KEY

Then reconfigure the system:

kctl tune