TikTok Events API Setup: Server-Side Tracking Guide

The TikTok Pixel is a JavaScript snippet that runs in your visitor’s browser. It works — when it works. But ad blockers, privacy browsers, iOS restrictions, and cookie consent settings all prevent the pixel from seeing every conversion.

The TikTok Events API sends conversion data directly from your server to TikTok’s servers. No browser involved. No JavaScript to block. No cookies to decline. It’s TikTok’s equivalent of Meta’s Conversions API.

If you’re spending real money on TikTok Ads and only using the pixel, you’re giving TikTok incomplete data. That means worse ad optimization, lower reported ROAS, and more wasted spend.

Why You Need the Events API

The browser pixel alone misses an increasing percentage of conversions:

Cause	% of Users Affected	Impact on Pixel
Ad blockers	15-30%	Pixel never loads
iOS App Tracking Transparency	~45% of iOS users opt out	Severely limited tracking
Privacy browsers (Brave, Firefox ETP)	5-10%	Cookies blocked or cleared
Cookie consent (GDPR)	20-50% in EU	Pixel disabled when consent denied
Network/script failures	2-5%	Pixel fails to fire

Combined, the pixel alone might miss 20-40% of your conversions. The Events API fills those gaps by sending data server-side.

When you run both the pixel and the Events API together, TikTok deduplicates the data (using event IDs) and uses whichever source captured the conversion. The result: more complete data, better optimization, and more accurate reporting.

How the Events API Works

The flow is straightforward:

1. Customer purchases on your website (or takes another conversion action)
2. Your server detects the purchase (via your e-commerce platform’s webhook, order creation event, etc.)
3. Your server sends the event data to TikTok’s Events API — including event name, timestamp, user identifiers (email, phone, IP, user agent), and event details (value, currency, content IDs)
4. TikTok receives the data and matches it to TikTok users using the provided identifiers
5. TikTok attributes the conversion to the ad that drove the user, and uses it for campaign optimization

The key difference from the pixel: step 2-4 happen entirely on the server side. The user’s browser is not involved.

What You Need Before Starting

1. A TikTok Ads account with an active pixel
2. A TikTok Business Center account (the pixel must be managed through Business Center)
3. Access token generated from TikTok Events Manager
4. Your Pixel ID (found in TikTok Events Manager)
5. A way to send server-side HTTP requests when conversions happen (your e-commerce platform, GTM server container, or custom code)

Setup Option 1: Shopify Integration

Shopify has a built-in TikTok channel app that supports the Events API natively.

1. Install the TikTok channel from the Shopify App Store
2. Connect your TikTok Business Center account
3. Enable Advanced matching and the TikTok Events API in the app settings
4. The app automatically sends purchase, add-to-cart, and checkout events server-side

Pros: No custom code. Handles deduplication automatically. Updated by Shopify. Cons: Limited to Shopify’s pre-defined events. Less control over what data is sent.

If you’re on Shopify, this is the fastest path to getting the Events API running. For a broader view of all Shopify tracking options, see our Shopify conversion tracking guide.

Setup Option 2: Google Tag Manager (Server-Side)

If you have a server-side GTM container, you can route TikTok Events API calls through it.

Step 1: Get Your Access Token

1. Go to TikTok Events Manager
2. Select your pixel
3. Click Settings
4. Under “Events API,” click Generate Access Token
5. Copy the token (you’ll need it for the GTM tag)

Step 2: Create the Server-Side Tag

In your server-side GTM container:

1. Go to Tags and create a new tag
2. Use a TikTok Events API tag template from the Community Template Gallery (or build a custom HTTP request tag)
3. Configure with your Pixel ID and Access Token
4. Map event parameters:
   • event: event name (e.g., CompletePayment)
   • event_id: unique ID for deduplication (must match the browser pixel’s event_id)
   • timestamp: ISO 8601 format
   • User data: email (hashed), phone (hashed), ip, user_agent
   • Content data: content_id, content_type, value, currency

Step 3: Set Up Deduplication

This is critical. Both your browser pixel and your Events API will send the same events. TikTok uses the event_id parameter to deduplicate them.

• Generate a unique event_id for each event occurrence
• Pass the same event_id to both the browser pixel and the Events API
• TikTok keeps whichever arrives first and ignores the duplicate

If you skip deduplication, every conversion gets counted twice. Your ROAS doubles overnight — but it’s fiction.

Setup Option 3: Direct API Integration

For developers who want full control, you can call TikTok’s Events API directly from your backend.

API Endpoint

POST https://business-api.tiktok.com/open_api/v1.3/event/track/

Request Headers

Content-Type: application/json
Access-Token: YOUR_ACCESS_TOKEN

Request Body (Purchase Example)

{
  "pixel_code": "YOUR_PIXEL_ID",
  "event": "CompletePayment",
  "event_id": "order-12345-purchase",
  "timestamp": "2026-04-01T14:30:00Z",
  "context": {
    "user_agent": "Mozilla/5.0 ...",
    "ip": "203.0.113.42",
    "page": {
      "url": "https://yourstore.com/checkout/thank-you",
      "referrer": "https://yourstore.com/checkout"
    },
    "user": {
      "email": "sha256_hashed_email",
      "phone_number": "sha256_hashed_phone",
      "external_id": "sha256_hashed_customer_id"
    }
  },
  "properties": {
    "currency": "USD",
    "value": 89.99,
    "contents": [
      {
        "content_id": "SKU-1234",
        "content_type": "product",
        "content_name": "Wireless Headphones",
        "quantity": 1,
        "price": 89.99
      }
    ],
    "content_type": "product"
  }
}

Important: Hash User Data

TikTok requires email addresses and phone numbers to be SHA-256 hashed before sending. Don’t send plaintext.

import hashlib

def hash_value(value):
    return hashlib.sha256(value.strip().lower().encode()).hexdigest()

hashed_email = hash_value("customer@example.com")

TikTok Event Names

TikTok uses different event names than GA4 or Meta. Map your events correctly:

Action	TikTok Event Name	GA4 Equivalent
Page view	ViewContent	page_view
Product view	ViewContent	view_item
Add to cart	AddToCart	add_to_cart
Start checkout	InitiateCheckout	begin_checkout
Add payment	AddPaymentInfo	add_payment_info
Purchase	CompletePayment	purchase
Registration	CompleteRegistration	sign_up

Verifying the Events API Is Working

TikTok Events Manager

1. Go to Events Manager and select your pixel
2. Click the Test Events tab
3. You should see events arriving with a “Server” source label (Events API) alongside “Browser” events (pixel)
4. Check that events show “Matched” status (TikTok successfully matched the user to a TikTok profile)

Match Quality Score

TikTok rates your event match quality. Higher scores mean better optimization:

Score	Assessment	Action
Great (8-10)	Strong match rates	Keep going
Good (5-7)	Decent but could improve	Add more user parameters
OK (3-4)	Low match rates	You’re missing key user data
Poor (1-2)	Very few matches	Check your implementation

To improve match quality:

• Always include hashed email when available
• Add hashed phone number
• Include IP address and user agent (your server has these)
• Add external_id (your customer ID, hashed)
• Include click_id (ttclid parameter from the TikTok click URL)

The ttclid parameter is especially important. When a user clicks a TikTok ad, TikTok appends ttclid=XXXXX to the URL. If you capture and send this back with the Events API, TikTok can match the conversion to the exact click with near-100% accuracy.

Troubleshooting

Events API Shows Events, But “Not Matched”

The user identifiers you’re sending don’t match any TikTok users. This happens when:

• Email addresses are hashed incorrectly (must be lowercase, trimmed, SHA-256)
• You’re sending placeholder or test data
• Your customer base doesn’t use TikTok heavily (B2B audiences, older demographics)

Duplicate Conversions

Your browser pixel and Events API are both counting conversions without deduplication. Fix: ensure both send the same event_id for each event occurrence.

Events API Returns Errors

HTTP Status	Meaning	Fix
400	Bad request (invalid parameters)	Check event name, data format
401	Invalid access token	Regenerate token in Events Manager
429	Rate limited	Batch events (up to 50 per request) or throttle sends

Events Delayed in Reporting

Events API data can take up to 15 minutes to appear in TikTok Events Manager. This is normal. Don’t panic if events don’t show up immediately.

For more on troubleshooting TikTok pixel issues (browser-side), see our TikTok pixel troubleshooting guide.

Events API vs Pixel: Use Both

This isn’t an either/or choice. Use both:

• The pixel provides real-time signals for audience building and real-time optimization
• The Events API fills gaps the pixel misses and provides more reliable conversion data
• Together with deduplication, TikTok gets the most complete picture of your conversions

TikTok’s ad algorithm performs measurably better with both data sources. Advertisers who implement the Events API alongside the pixel typically see improved ROAS because the algorithm has better data to optimize against.

The Bottom Line

If you’re spending money on TikTok Ads, the Events API is not optional — it’s the foundation of accurate measurement. The browser pixel alone misses too many conversions, and those missed conversions mean worse ad optimization and inaccurate ROAS reporting.

The setup takes a few hours. The improvement in data quality is permanent. And unlike creative testing, which requires ongoing experimentation, this is a one-time infrastructure investment that pays off on every campaign you run.

For information on how server-side tracking works across all platforms, see our server-side tracking explained guide. And if you want to check whether your current TikTok tracking is working correctly, run a free scan.