# Retargeting pixels (Business+)

Source: https://developers.leonai.io/docs/guides/retargeting-pixels/

Attach advertising retargeting pixels to your short links so visitors who click can be
added to your ad audiences. You register a pixel once (per ad platform), then attach it
to any number of links. When a **Business+** owner's link has pixels, the redirect serves
a short JavaScript interstitial that fires the pixels and then forwards the visitor to the
destination.

Managing pixels requires `links:write`. Pixels are a **Business+** feature — requests from
lower tiers return `403`.

## Supported providers

| `provider`   | Platform              |
| ------------ | --------------------- |
| `meta`       | Meta / Facebook Pixel |
| `google_ads` | Google Ads            |
| `linkedin`   | LinkedIn Insight Tag  |
| `tiktok`     | TikTok Pixel          |
| `twitter`    | X / Twitter Pixel     |

## Register a pixel

```bash
curl -X POST https://api.short.leonai.io/api/v1/pixels \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "meta",
    "pixelId": "1234567890",
    "name": "Main Meta Pixel",
    "enabled": true
  }'
```

Response (`201 Created`):

```json
{
  "success": true,
  "data": {
    "id": "pix_...",
    "provider": "meta",
    "pixelId": "1234567890",
    "name": "Main Meta Pixel",
    "enabled": true,
    "createdAt": "2026-07-11T12:00:00.000Z"
  }
}
```

`REST: POST /api/v1/pixels`. Manage pixels with `GET /api/v1/pixels`,
`PATCH /api/v1/pixels/:id`, and `DELETE /api/v1/pixels/:id`.

## Attach pixels to a link

A link can carry up to **20** pixels. Set the full list with `PUT`:

```bash
# See which pixels are attached
curl https://api.short.leonai.io/api/v1/links/<linkId>/pixels \
  -H "X-API-Key: $LEONAI_API_KEY"

# Replace the attached set
curl -X PUT https://api.short.leonai.io/api/v1/links/<linkId>/pixels \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "pixelIds": ["pix_1", "pix_2"] }'
```

`REST: GET /api/v1/links/:linkId/pixels` and `PUT /api/v1/links/:linkId/pixels`.

## How the redirect behaves

When a Business+ owner's link has one or more enabled pixels attached, the redirect no
longer returns a bare `302`. Instead it serves a small **GPC-aware JavaScript
interstitial** that:

1. Checks the visitor's consent signal (see below).
2. If tracking is allowed, fires each attached pixel.
3. Forwards the visitor to the destination URL.

Links without pixels — and links owned by non-Business+ accounts — keep the fast direct
redirect.

## Consent & Global Privacy Control (Sec-GPC)

Pixel firing is **consent-aware**. If the request carries the **`Sec-GPC: 1`** header (the
[Global Privacy Control](https://globalprivacycontrol.org/) opt-out signal sent by
privacy-respecting browsers), the interstitial **skips firing the pixels** and forwards
the visitor straight through. This keeps retargeting compliant with GDPR/CCPA opt-outs
without any extra configuration on your side. Visitors who have not opted out are
retargeted normally.

## Error codes

| Status | When                                                              |
| ------ | ----------------------------------------------------------------- |
| `400`  | Unknown `provider`, missing `pixelId`, or more than 20 `pixelIds` |
| `403`  | Account is not on Business+ (feature gated)                       |
| `404`  | Pixel or link not found / not owned by you                        |

## Related

- [Links](https://developers.leonai.io/docs/guides/links/) — the links these pixels attach to
- [Billing](https://developers.leonai.io/docs/guides/billing/) — Business+ features
- [API Reference](https://developers.leonai.io/docs/api-reference/) — the full OpenAPI spec and Swagger UI