> For the complete AppRefer docs index, see https://apprefer.com/llms.txt (every page as markdown) or https://apprefer.com/llms-full.txt (all docs in one file).

# X Ads

Website conversions from your payment backend to the X Ads Web Conversion API, attributed to the X click that brought the buyer.

> **Off until you turn it on**
>
> The X integration is website-only and disabled for every app by default. Saving credentials never enables it and never calls X. Forwarding starts only after you send `enabled: true`. Spend import is not part of this integration.

## How it works

1.  Your X ad points to `https://apprefer.com/x/{linkId}`. X appends its click ID `twclid`.
2.  AppRefer records the click only when a valid `twclid` is present and the browser did not send a Global Privacy Control opt-out, then sends the visitor to your website with `ar_click_id`and the same `twclid` (for your X pixel).
3.  After a settled payment, your backend posts a verified receipt to `/api/v1/apps/{appId}/web-events` (see [web events](https://apprefer.com/docs/events.md#verified-website-payments)) with that `arClickId`. Web events must be turned on for the app first.
4.  AppRefer sends one conversion to X with the original `twclid`, your Ads Manager event ID and your own `eventId` as `conversion_id`.

## 1\. Create the tracking link

Use network `x_ads` (not `x` or `twitter`, which stay ordinary redirect links for organic posts). X links must be `web_funnel` links whose `storeUrl` is a clean HTTPS page on your website with no query, fragment or credentials.

**X Ads destination**

```
https://apprefer.com/x/{linkId}
→ https://yoursite.com/?twclid=…&utm_source=x_ads&ar_click_id=…&ar_link_id=…
```

## 2\. Configure the integration

X is configured through the REST API or the MCP tool `configure_integration` (network `x_ads`); there is no dashboard form yet. Send any subset; omitted fields keep their stored value. Unknown fields are rejected with 400. The four OAuth 1.0a values come from an X developer app with Ads API access for the account that owns the pixel. They are encrypted at rest and masked on every read. `eventIds` merges per key; send `""` or `null` to unmap one.

**PATCH /api/v1/apps/{appId}/integrations/x_ads (integrations:write)**

```bash
curl -X PATCH https://apprefer.com/api/v1/apps/$APP_ID/integrations/x_ads \
  -H "Authorization: Bearer $AK_LIVE_KEY" -H "Content-Type: application/json" \
  -d '{
    "pixelId": "o8z6j",
    "eventIds": { "purchase": "tw-o8z6j-o8z6k" },
    "consumerKey": "…", "consumerSecret": "…",
    "accessToken": "…", "accessTokenSecret": "…",
    "enabled": true
  }'
```

| Field | Meaning |
| --- | --- |
| enabled | Only the boolean true turns forwarding on. Default false. |
| pixelId | X pixel ID (letters and digits). |
| eventIds | purchase, complete\_registration, initiate\_checkout, start\_trial → the Ads Manager event ID, stored as entered. |
| consumerKey, consumerSecret, accessToken, accessTokenSecret | OAuth 1.0a user-context credentials. Secret. |
| connected (read only) | Pixel ID, all four credentials and at least one event ID are stored. It is not a check against X. |

## Event mapping

| web-events eventType | X event (only if mapped) | Value |
| --- | --- | --- |
| purchase | eventIds.purchase | revenue + currency, number\_items 1 |
| sign\_up | eventIds.complete\_registration | none |
| checkout\_started | eventIds.initiate\_checkout | selected price + currency |
| start\_trial | eventIds.start\_trial | predicted value + currency |
| renewal, refund | Never sent | Warehouse only |

Each paid order is its own `purchase` receipt. A one-off purchase and a later upsell (for example a second version) are two receipts with two `eventId`s, and reach X as two Purchase conversions, each with its own value and currency.

## Deduplication with the X pixel

AppRefer sends your receipt `eventId` unchanged as `conversion_id`. If your website also fires the X pixel for the same order, give the pixel the same value as its `conversion_id` so X can count the order once. Retries reuse the same `conversion_id`.

## Delivery and privacy

-   POST https://ads-api.x.com/12/measurement/conversions/{pixelId}, OAuth 1.0a HMAC-SHA1, one conversion per request.
-   Identifiers: `twclid`, optional `hashed_email` from `emailSha256`, and the click's IP and browser user agent as a pair when known.
-   408, 429, 5xx and network errors stay queued and retry with the same IDs until the receipt is seven days old; other 4xx responses and a 2xx that reports the conversion unprocessed are final.
-   Forwarding logs keep only flags, the event and conversion IDs, value and an X error code: never the click ID, hashes, IP, user agent, credentials or X's response body.
-   X never receives Meta, TikTok, Google, ChatGPT Ads, organic or app-store events.

---

Source: https://apprefer.com/docs/integrations/x · Last updated: 2026-10-19