Tracking S2S Postback

An S2S postback is a request the advertiser’s server sends directly to PalDock. No browser, no cookies, nothing to block. It is the most reliable way to receive conversions and the method we recommend to every advertiser, on its own or alongside a pixel.

The endpoint

https://api.paldock.com/api/tenant-name/postbacks/handle

Three ways to identify the conversion:

By Origin ID

?origin_id={origin_id}&type={sale}&result={approved}&action={create}

By Advertiser ID and External ID

?advertiser_id={advertiser_id}&external_id={your_external_id}&type={sale}&result={approved}&action={create}

By both, which we recommend

?origin_id={origin_id}&advertiser_id={advertiser_id}&external_id={your_external_id}&type={sale}&result={approved}&action={create}

Affiliate links can only use the Origin ID, because the external ID does not exist yet at click time. iFrame and API integrations can use either. See Conversion IDs explained.

The main parameters

• type: the conversion type. Required when creating.
• action: create or update. Without it, the request is treated as a create.
• result: approved, rejected, or pending. Sending it on an update changes the transaction result.
• value: the order value, used by percentage commissions.
• commission: the payout amount, when the advertiser calculates it themselves.
• external_id: the advertiser’s own order ID. Always ask for it, even when the Origin ID is sent.
• commission_id: which commission applies, when the type has more than one.
• postback_id: which postback the request belongs to. Required when that postback has a scenario.
• create=false: refuse to create anything if the update finds no conversion.

The full list is on Tracking parameters.

Postbacks and conditions

A global postback exists by default with every condition set to All, so an advertiser can start sending immediately. Create your own when you need different handling for different partners.

Conditions decide whether a request is accepted:

• Source: All, Link, iFrame, API
• Conversion type: All, Prospect, Sale, or a custom type
• Affiliate: All or specific
• Advertiser: All or specific
• Offer: All or specific

A request that does not match the conditions is logged as Filtered and nothing happens.

Postbacks appear in the postback table with the country inherited from the offer. When no offer or several offers are selected, the global country applies and the category stays blank.

Scenarios

Some advertisers only tell you that something changed, without saying what. A scenario lets the postback call them back and fetch the rest, or transform the incoming data before it is stored.

Two common uses:

• Fetching missing data: the advertiser sends an ID, PalDock calls their API for the status and the value.
• Mapping parameter names: the advertiser sends their own names and their own status values, and the scenario translates them into PalDock’s.

⚠️ When a postback has a scenario, postback_id becomes mandatory. Without it the request is still received, but the scenario does not run. Ask the advertiser to add it to the URL, for example ?postback_id=value.

See Connection Creator in Tracking.

Creating and updating

• Create records a new conversion and needs type.
• Update changes an existing one, typically to set the result or the value.
• An update that finds no conversion creates one instead, as long as type is present and create=false is not.

An advertiser who reports a sale on a click or a lead does not overwrite it. PalDock creates a sale conversion under it. See Tracking processing.

What comes back

• 200: something changed.
• 204: accepted, but nothing changed. Usually the values were already stored.
• 400: an update that found no conversion.
• 422: the request failed validation.

Treat 204 as a warning. See Tracking errors and reasons.