# Tracking links and postbacks

Short links that record each click, split traffic across landing pages and take conversions from affiliate networks by postback.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

A tracking link records each click and sends it on to a landing page with a click id. Conversions come back through your site's tag, or from an affiliate network by postback.

## Before you start

A link belongs to a [tracking site](/products/server-side-tracking/install). It uses the site's [custom subdomain](/products/server-side-tracking/custom-subdomain) once that is active, so the click cookie is first-party.

## Create a link

`POST /v1/tracking-links` takes the site, a name and up to 10 destinations. Each click goes to one destination, picked by `weight`, so one link also split-tests landing pages.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.trackinglinks.createTrackingLink({
  headers: { 'Idempotency-Key': crypto.randomUUID() },
  body: {
    siteId: '66c3a1b2c3d4e5f6a7b8c9d0',
    name: 'Black Friday',
    destinations: [
      { url: 'https://shop.example.com/bf-a', weight: 50 },
      { url: 'https://shop.example.com/bf-b', weight: 50 }
    ],
    campaign: { platform: 'metaads', utmCampaign: 'black_friday' }
  }
});
```
</Tab>
<Tab value="Python">
```python
import uuid

data = client.tracking_links.create_tracking_link(
    idempotency_key=str(uuid.uuid4()),
    site_id="66c3a1b2c3d4e5f6a7b8c9d0",
    name="Black Friday",
    destinations=[
        {"url": "https://shop.example.com/bf-a", "weight": 50},
        {"url": "https://shop.example.com/bf-b", "weight": 50},
    ],
    campaign={"platform": "metaads", "utmCampaign": "black_friday"},
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/tracking-links" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "siteId": "66c3a1b2c3d4e5f6a7b8c9d0",
    "name": "Black Friday",
    "destinations": [
      { "url": "https://shop.example.com/bf-a", "weight": 50 },
      { "url": "https://shop.example.com/bf-b", "weight": 50 }
    ],
    "campaign": { "platform": "metaads", "utmCampaign": "black_friday" }
  }'
```
</Tab>
</Tabs>

Response (`201`):

```json
{
  "link": {
    "id": "66d4b2c3d4e5f6a7b8c9d0e1",
    "name": "Black Friday",
    "code": "aB3dE5fG",
    "status": "active",
    "url": "https://t.example.com/r/aB3dE5fG",
    "postbackUrl": "https://t.example.com/pb/pbt_9f8e7d6c5b4a?clickid={clickid}&payout={payout}&txid={txid}",
    "destinations": [
      { "url": "https://shop.example.com/bf-a", "weight": 50 },
      { "url": "https://shop.example.com/bf-b", "weight": 50 }
    ],
    "campaign": { "platform": "metaads", "utmCampaign": "black_friday" }
  }
}
```

`campaign` is optional. It ties the link's conversions to an ad campaign when the click itself carries no UTM tag or click id.

## What a click does

Put `url` in your ad. Each click on it:

1. Picks a destination by weight. A returning visitor gets the same one again.
2. Passes on the click's own parameters: ad click ids, UTM tags, `sub1` to `sub5`. The destination's own parameters win.
3. Adds `zcid`, a click id minted for this click.
4. Redirects with a `302`, and records the click after the response.

A paused link still redirects, always to its first destination, but records nothing. Bots are redirected and never counted.

## Send the click id to an affiliate network

An affiliate network returns only its own sub parameters, never `zcid`. Put `{zcid}` in the parameter the network passes back, and each click fills in its click id.

```
https://network.example/click?offer=123&aff=456&sub1={zcid}
```

The network then sends it back in `{sub1}`, its macro for that parameter.

## Take conversions by postback

Give the network `postbackUrl`, with each `{placeholder}` replaced by the network's own macro:

| Parameter | What it carries |
|---|---|
| `clickid` | Required: the `zcid` you sent the network |
| `payout` | The conversion's value, 0 or more |
| `currency` | ISO code. `USD` when a payout comes without one |
| `txid` | The network's transaction id. A repeated postback with it replaces the conversion |
| `event` | The event name. `sale` becomes `Purchase` and `lead` becomes `Lead`. `Purchase` when absent |
| `status` | Absent or approved-like records it. Rejected-like retracts it. Anything else is ignored |

Rejected-like statuses are `rejected`, `declined`, `refunded`, `reversed` and `chargeback`. A `pending` postback is answered `200` and changes nothing, so send the approved one later.

The postback answers `GET` and form `POST`, and returns `200 OK` once the conversion is accepted.

## Postback URLs per network

Replace `pbt_…` with your link's token.

| Network | Click id parameter on the offer link | Postback URL |
|---|---|---|
| Everflow | `sub1={zcid}` | `…/pb/pbt_…?clickid={sub1}&payout={payout_amount}&txid={transaction_id}` |
| TUNE (HasOffers) | `aff_sub={zcid}` | `…/pb/pbt_…?clickid={aff_sub}&payout={payout}&txid={transaction_id}` |
| CAKE | `s2={zcid}` | `…/pb/pbt_…?clickid=#s2#&payout=#price#&txid=#tid#` |
| MaxBounty | `s2={zcid}` | `…/pb/pbt_…?clickid=#S2#&payout=#RATE#` |

Macro names can differ per network account. Check your network's macro list when a test conversion does not arrive.

## Read a link's results

`GET /v1/tracking-links/{linkId}/stats?fromDate=2026-11-01&toDate=2026-11-19` returns clicks, conversions, conversion rate and revenue per currency, and clicks per destination.

Conversions are the link's postbacks plus website conversions that carry one of its click ids, less retracted ones. The range is at most 90 days, the time clicks are kept.

Postback conversions also count in [campaign results](/guides/campaign-results) for the link's campaign. They are not forwarded to ad platforms.

## How it behaves

- **The token is a secret.** Anyone holding `postbackUrl` can post conversions to the link. Rotate it with `POST /v1/tracking-links/{linkId}/rotate-postback-token` if it leaks.
- **Postbacks are namespaced by link.** A postback can replace only conversions of its own link.
- **Rate limits.** A link answers `429` with `Retry-After` past its postback limit, and networks retry.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| Postback `400 Missing clickid` | The network sent no click id | Map the network's macro to `clickid`. |
| Postback `400 Invalid clickid` | The macro stayed unfilled, such as `{sub1}` | Check that the offer link carries `{zcid}` in that sub parameter. |
| Postback `404 Unknown postback` | The token was rotated or the link deleted | Give the network the current `postbackUrl`. |
| Link `404 Link not found` | Unknown code, or the site is not active | Check `url`, and that the site is live. |
| Conversions `0` while the network shows sales | The postback status was `pending`, or the macros are wrong | Send approved postbacks, then read the network's postback log. |

## Related

- [Install the tag](/products/server-side-tracking/install): the site a link belongs to.
- [Custom subdomain](/products/server-side-tracking/custom-subdomain): first-party links on your own domain.
- [Campaign results](/guides/campaign-results): where postback conversions count.
- [Create a tracking link](/tracking-links/create-tracking-link): every field.