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

Your X ad points to https://apprefer.com/x/{linkId}. X appends its click ID twclid.
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_idand the same twclid (for your X pixel).
After a settled payment, your backend posts a verified receipt to /api/v1/apps/{appId}/web-events (see web events) with that arClickId. Web events must be turned on for the app first.
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)Terminal

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 eventIds, 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.