TikTok Events API for F2F creators

Why TikTok tracking needs a server

TikTok is one of the fastest-growing acquisition channels for F2F creators, and it is also one of the hardest to measure. Almost every TikTok ad click opens inside the TikTok in-app browser, which keeps its own isolated cookie jar. When a fan later completes a subscription on F2F.com, often in a different browser or after switching apps, the TikTok Pixel has no way to connect that purchase back to the click. On iOS, App Tracking Transparency further limits what TikTok can observe.

The TikTok Events API lets a server report conversions directly. F2F API captures the ttclid click identifier on your tracking link, waits for the corresponding F2F transaction, and then sends a fully formed event to TikTok with the click ID in the callback field and hashed customer identifiers attached. TikTok's attribution system uses those signals to credit the right campaign, ad group and creative, which in turn gives the TikTok delivery algorithm the feedback it needs to find more fans like your best spenders.

Advertisers who combine the Pixel with the Events API typically see a meaningful increase in attributed conversions and a lower reported cost per acquisition, simply because conversions that were always happening are finally counted.

Core identifiers

• ttclid: the click identifier TikTok appends to ad destination URLs. Store it on the first page view and send it as context.ad.callback.
• _ttp: the TikTok Pixel browser cookie. Send it as context.user.ttp when the Pixel runs on your link page.
• Hashed email: trimmed, lowercased and SHA-256 hashed, sent as context.user.email.
• Hashed phone number: normalized to E.164 format (for example +15551234567) and SHA-256 hashed.
• Pixel code: the identifier of the TikTok pixel that receives events, such as C4ABCDEF1234567890.
• Events API access token: a long-lived token generated in TikTok Events Manager. It authorizes writes to the pixel and must stay on the server.

The client IP address and user agent captured at click time are also sent, unhashed, in context.ip and context.user_agent. They help TikTok match events when no click ID is present.

Step 1: Create the pixel and access token

1. In TikTok Ads Manager, open Tools, then Events, then Web Events.
2. Choose Set up web events, name the pixel after the creator, and select Events API as the connection method (you can add the Pixel later for combined tracking).
3. On the pixel settings page, choose Generate Access Token. Copy the token; it does not expire unless you regenerate it.
4. Copy the pixel code shown at the top of the page.
5. In your F2F API dashboard, open Ads Tracking, choose TikTok, and paste the pixel code and token. F2F API encrypts the token at rest.

One pixel per creator is the recommended structure. It keeps optimization signals separate and makes it easy to hand reporting to the creator directly.

Step 2: Capture ttclid on your tracking link

The ttclid parameter only exists on the very first page the fan lands on. If your link page redirects or the fan taps a second link, it is gone. Capture it server-side in a first-party cookie so it survives the in-app browser session, and forward it to F2F API with the click record:

# Verify your tracking link sets the first-party _ttclid cookie
curl -I "https://link.yourdomain.com/go/creator?ttclid=TEST_CLICK_123"

# Expected response header:
# Set-Cookie: _ttclid=TEST_CLICK_123; Path=/; Max-Age=7776000; SameSite=Lax; Secure

Setting the cookie from your own server rather than from JavaScript matters on iOS, where Safari's Intelligent Tracking Prevention caps script-written cookies at seven days. A server cookie on your own domain lasts the full 90 days, which covers late subscribers who come back a few weeks after the first click.

Step 3: Event mapping

TikTok supports a set of standard events. F2F API uses these by default:

• ViewContent: tracking link visit.
• ClickButton: fan taps the subscribe button on your link page.
• SubmitForm: free follow or email capture.
• Subscribe: new paid subscription on F2F.
• CompletePayment: PPV unlock, tip or renewal, sent with the real value and currency.

For campaign optimization, TikTok recommends choosing an event that fires at least 50 times per week per ad group. Small creators often start with Subscribe and move to CompletePayment with value optimization once volume grows.

Step 4: Payload example

F2F API builds and sends this request for you, but understanding the payload helps when debugging. Events go to POST https://business-api.tiktok.com/open_api/v1.3/event/track/ with the Access-Token header:

curl -X POST "https://business-api.tiktok.com/open_api/v1.3/event/track/" \
  -H "Content-Type: application/json" \
  -H "Access-Token: YOUR_TIKTOK_EVENTS_API_TOKEN" \
  -d '{
    "event_source": "web",
    "event_source_id": "C4ABCDEF1234567890",
    "data": [
      {
        "event": "CompletePayment",
        "event_time": 1767225600,
        "event_id": "evt_5c1d7e",
        "user": {
          "email": "SHA256_OF_LOWERCASE_EMAIL",
          "phone": "SHA256_OF_E164_PHONE",
          "ttclid": "E.C.P.abc123",
          "ttp": "2Xy9...",
          "ip": "203.0.113.24",
          "user_agent": "Mozilla/5.0 (iPhone)"
        },
        "properties": {
          "currency": "USD",
          "value": 24.99,
          "content_type": "product",
          "contents": [
            {
              "content_id": "ppv_7781",
              "quantity": 1,
              "price": 24.99
            }
          ]
        },
        "page": {
          "url": "https://link.yourdomain.com/go/creator"
        }
      }
    ]
  }'

In the v1.3 format the click ID travels in user.ttclid; older integrations send it as context.ad.callback. F2F API sends the format that matches your pixel's API version automatically. All identifiers marked SHA256 are hashed by F2F API before transmission. Never send raw email or phone values.

Step 5: Deduplicate Pixel and Events API

If the TikTok Pixel also runs on your link page, give each browser event an event_id and send the same value in the server event. TikTok deduplicates events that share the same event name and event_id within a 48-hour window. For purchases that only happen on F2F.com there is no Pixel event, and F2F API derives the event ID from the F2F transaction ID so that retries never double count.

Step 6: Validate with test event codes

In Events Manager, open your pixel and select the Test Events tab. TikTok shows a test event code such as TEST98765. Add it to your F2F API TikTok settings or include test_event_code in a manual request. Events sent with the code appear in the Test Events panel within seconds and are excluded from reporting and optimization.

Verify that each event displays the expected name, value and currency; that the click ID and hashed email show as received; and that the match quality indicator is green. Then remove the test code to go live. After launch, the Diagnostics tab in Events Manager will flag issues such as missing parameters or duplicate events, and F2F API request logs show the TikTok response code and message for every event.

Understanding TikTok response codes

The TikTok API returns HTTP 200 for almost every request and reports success or failure in the JSON body. A code of 0 means the event was accepted. Non-zero codes indicate problems such as an invalid token, a malformed timestamp or an unknown pixel. F2F API surfaces the TikTok code and message in the request log so you never mistake a rejected event for a successful one.

Going live checklist

Before you raise budgets on a creator, walk through this short checklist. It catches nearly every issue agencies hit in their first week with the TikTok Events API.

1. Click a live ad on a real phone and confirm the landing request contains ttclid in the server logs of your tracking link.
2. Confirm the response sets the _ttclid cookie on your own domain with a 90-day lifetime.
3. Open the F2F API click log and check that the click record shows the click ID, IP address and user agent.
4. Make a small test purchase or use a sandbox transaction and confirm the CompletePayment event appears in Test Events with the click ID attached.
5. Remove the test event code, then compare TikTok reported conversions with the F2F API conversion report after 48 hours.

A gap of a few percent between TikTok and F2F API is normal, because TikTok only credits conversions inside its attribution window and only for users it can match. A gap of more than 30% usually points to click IDs being dropped by a redirect or link shortener, which you can confirm by filtering the F2F API click log for visits from TikTok without a click ID.

How F2F API handles retries

If TikTok returns an error or times out, F2F API retries the event with exponential backoff for up to 24 hours, reusing the same event ID so that a late success never creates a duplicate. Permanent errors such as an invalid pixel code stop retrying immediately and raise an alert in your dashboard and through the capi.delivery_failed webhook, so a broken token never silently costs you a weekend of attribution.

Troubleshooting

Attribution windows

TikTok's default attribution window is 7-day click and 1-day view. Subscribers who convert later than seven days after clicking will still be reported through the Events API, but may not be credited to the campaign. If your funnel has a long consideration period, review the attribution settings in Ads Manager and compare them with the F2F API conversion lag report, which shows the time between click and purchase for each creator.

Privacy

Display a cookie notice on your link pages, skip click ID storage for visitors who opt out, and only send identifiers you are permitted to share. F2F API hashes all personal identifiers and lets you disable phone or email matching per pixel.