Postback API

A postback is a request from the advertiser’s server to Postbackly saying “this click became a sale”. No pixel, no cookie, nothing in the visitor’s browser.

Overview

A visitor arrives on the landing page through a Postbackly link, with pbclid=… in the URL (see the redirect documentation).
Your site keeps that value with the visitor’s session or order, on your own domain.
When the order is confirmed, your server calls the postback URL with the pbclid as click_id.
Postbackly records a conversion for the click’s offer, publisher and sub IDs, with status pending.

Endpoint

https://go.postbackly.click/postback?click_id={pbclid}&txid={order_id}&payout={amount}&key=YOUR_OFFER_KEY

GET with query parameters, or POST with an application/x-www-form-urlencoded body. HTTPS only. Replace YOUR_OFFER_KEY with the postback key shown on the offer in your dashboard, and the {…} placeholders with your platform’s own variables.

Parameters

Name	Required	Description
`click_id`	yes*	The `pbclid` value the landing page received.
`gclid`	*	Only when the landing page has no `pbclid` (Google Ads parallel tracking, see below): the `gclid` Google Ads added to the landing URL. It is matched to the click that carried the same `gclid` on the tracking link, so keep `gclid={gclid}` in the tracking template. *Send `click_id` or `gclid`; if both are sent, `click_id` is used.
`key`	yes	The secret postback key of the offer the click belongs to.
`txid`	no	Your order or transaction ID. Unique per offer: the same `txid` is recorded only once. Without it, each click can have only one conversion.
`payout`	no	Commission for this conversion, as a number (for example `45000` or `12.5`). If missing, the offer’s default payout is used.
`currency`	no	Three-letter currency code such as `VND` or `USD`. Each account reports in one currency, set in the dashboard. If sent, it must match that currency, otherwise the postback is refused with `400`; amounts are never converted.

Do not add a parameter named url: on the tracking domain, url is reserved for redirects, and a request carrying it is treated as a click, not a postback.

Examples

GET

curl "https://go.postbackly.click/postback?click_id=Rk7pW2xQa9Lm_3Tc&txid=A1043&payout=45000&key=YOUR_OFFER_KEY"

POST form

curl -X POST "https://go.postbackly.click/postback" \
  -d click_id=Rk7pW2xQa9Lm_3Tc -d txid=A1043 -d payout=45000 -d currency=VND -d key=YOUR_OFFER_KEY

Response

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok","conversion_id":1287}

Responses

Every response is JSON.

Status	Meaning	What to do
200	Conversion recorded. The body contains `conversion_id`.	Done.
400	A required parameter is missing or a value is malformed (for example a payout that is not a number).	Fix the request; do not retry it unchanged.
403	The key does not match the click’s offer, or the offer or account is suspended.	Check the key in your dashboard.
404	No click with this `click_id` (or `gclid`), or the click is older than 90 days.	Check that you send the pbclid unchanged; do not retry.
409	This `txid` is already recorded for this offer (or, without `txid`, this click already has a conversion).	Already counted. Stop retrying.

Duplicates and retries

Postbacks are idempotent by txid. If your server times out or is unsure whether a postback arrived, send it again with the same txid: you get 200 the first time and 409 afterwards, never a second conversion. Retry on network errors and 5xx responses, with increasing delays; do not retry 400, 403 or 404.

For several conversions from one click, such as a second purchase, send each with its own txid.

Keeping the key safe

Each offer has its own key, so one leaked key cannot create conversions on your other offers.
Send postbacks only from your server. Never put the key in a browser pixel, JavaScript, a mobile app or a page that visitors can view.
Prefer POST: query strings are more likely to end up in logs along the way.
We compare keys in constant time and record a postback only when the key matches the click’s offer.
If you think a key has leaked, write to contact@postbackly.click and pause the offer until it is replaced; you can still reject any conversion you did not expect.

pbclid itself is not a secret: it appears in the landing page URL. The key is what proves a postback comes from you.

Approval and reconciliation

pending→approvedorrejected

Every conversion starts as pending. For a payout period, the advertiser or network approves or rejects conversions one by one or in bulk, for example rejecting cancelled orders. The reconciliation view shows pending, approved and rejected totals per publisher, and exports a CSV to pay from.

Postbackly only keeps the records. We do not hold, collect or transfer commission money; payment is between you and your publishers.

Test checklist

Open a publisher link yourself and check that the landing page URL ends with pbclid=….
Send a postback with that value and a test txid: expect 200.
Send the same request again: expect 409.
Find the conversion in your reports as pending, then reject it so it does not count.