TikTok Events API: Complete Setup Guide for E-Commerce

What is TikTok Events API?

TikTok Events API is a server-side tracking interface that lets you send conversion events directly from your server to TikTok — bypassing the browser entirely. It's TikTok's equivalent of Meta's Conversions API (CAPI) and Google's Enhanced Conversions, designed to solve the same core problem: browser-side tracking is losing data.

When you run TikTok ads, the standard TikTok Pixel (a JavaScript snippet in the browser) tracks user actions like page views, add-to-carts, and purchases. But that pixel is increasingly unreliable.

Why the TikTok Pixel alone isn't enough

The result: Your TikTok Ads Manager is likely missing 20-40% of actual conversions. That incomplete data cripples TikTok's ad optimization algorithm — leading to higher CPAs and wasted ad spend.

Events API fixes this by sending conversion data from your server, where none of these browser-side issues apply.

---

How TikTok Events API Works

Standard tracking (pixel-only)

User clicks TikTok ad → lands on your site → TikTok Pixel fires (JavaScript)
→ User converts → Pixel sends event to TikTok → Conversion recorded

Problem: If the pixel is blocked, doesn't load, or the user switches devices — the conversion is lost.

Events API (server-side)

User clicks TikTok ad → lands on your site → Your server captures the visit
→ User converts → Your server sends event to TikTok via HTTPS
→ TikTok matches hashed user data to the original ad click
→ Conversion recorded — regardless of ad blockers, cookies, or devices

Result: Your server communicates directly with TikTok's servers. Ad blockers, browser restrictions, and device switching don't affect the data flow.

What data gets sent?

Events API sends two types of data with each event:

Event data:

• Event name (e.g., CompletePayment, AddToCart, ViewContent)
• Event ID (for deduplication)
• Timestamp
• Page URL and referrer
• Content details (product ID, price, quantity)

User data (hashed for privacy):

Important: Email and phone are SHA-256 hashed before sending. TikTok never receives raw personal data — only irreversible hashes used for matching.

---

TikTok Events API vs. Meta CAPI vs. Google Enhanced Conversions

If you're already using Meta CAPI or Google Enhanced Conversions, the concept is identical. Here's how they compare:

Key takeaway: If you're advertising on multiple platforms, you need server-side tracking for each one. Each platform's algorithm can only optimize on the data it receives.

---

Setup Method 1: Manual Implementation

This method requires developer resources and ongoing maintenance but gives you full control.

Step 1: Create a TikTok for Business Account

1. Go to TikTok for Business and create an account
2. Navigate to Events Manager in TikTok Ads Manager
3. Click Connect Data Source → Web → TikTok Pixel
4. Create a new pixel or select an existing one
5. Note your Pixel Code (e.g., D6FF5SRC77U0SFL8LS8G)

Step 2: Generate an Events API Access Token

1. Go to the TikTok for Business Developer Portal
2. Create a new app or select your existing one
3. Under Scope of Permission, enable:
   • Measurement → Report Pixel Event (grants access to /event/track/)
   • Pixel Management → Read Pixels (for pixel discovery)
4. Generate an access token for your advertiser account
5. Store the access token securely — you'll need it for API calls

Step 3: Capture the TikTok Click ID (ttclid)

When a user clicks your TikTok ad, TikTok appends a ttclid parameter to your landing page URL. You need to capture and store this:

// On your landing page — capture ttclid from URL
const urlParams = new URLSearchParams(window.location.search);
const ttclid = urlParams.get('ttclid');
if (ttclid) {
  // Store in first-party cookie or session
  document.cookie = `ttclid=${ttclid}; max-age=${60 * 60 * 24 * 7}; path=/; SameSite=Lax`;
}

The ttclid is the most valuable matching signal — it directly ties the conversion back to the specific ad click.

Step 4: Send Events to TikTok

When a conversion happens (purchase, add to cart, etc.), send it to TikTok from your server:

import hashlib
import requests
import time

PIXEL_CODE = "YOUR_PIXEL_CODE"
ACCESS_TOKEN = "YOUR_ACCESS_TOKEN"

def sha256_hash(value):
    """Hash and normalize data before sending"""
    return hashlib.sha256(value.strip().lower().encode()).hexdigest()

def send_tiktok_event(event_name, user_email, user_phone, ttclid,
                      page_url, user_agent, ip_address,
                      value=None, currency="USD", event_id=None):
    url = "https://business-api.tiktok.com/open_api/v2/pixel/track/"
    
    event = {
        "pixel_code": PIXEL_CODE,
        "event": event_name,
        "event_id": event_id or f"{event_name}_{int(time.time())}",
        "timestamp": int(time.time()),
        "context": {
            "user_agent": user_agent,
            "ip": ip_address,
            "page": {
                "url": page_url
            }
        },
        "user": {}
    }
    
    # Add hashed user data
    if user_email:
        event["user"]["email"] = sha256_hash(user_email)
    if user_phone:
        event["user"]["phone"] = sha256_hash(user_phone)
    if ttclid:
        event["user"]["ttclid"] = ttclid
    
    # Add conversion value for purchase events
    if value is not None:
        event["properties"] = {
            "value": value,
            "currency": currency
        }
    
    response = requests.post(
        url,
        json={"data": [event]},
        headers={
            "Access-Token": ACCESS_TOKEN,
            "Content-Type": "application/json"
        }
    )
    
    return response.json()

# Example: Send a purchase event
result = send_tiktok_event(
    event_name="CompletePayment",
    user_email="customer@example.com",
    user_phone="+14155551234",
    ttclid="E.C.P.abc123xyz",
    page_url="https://yourstore.com/thank-you",
    user_agent="Mozilla/5.0...",
    ip_address="203.0.113.42",
    value=89.99,
    currency="USD",
    event_id="order_12345"
)

Step 5: Implement Event Deduplication

If you run both the TikTok Pixel (browser) and Events API (server) — which TikTok recommends — you must deduplicate events to prevent double-counting.

The key is using the same event_id for both the browser pixel event and the server API event:

Browser-side (TikTok Pixel):

// Generate a unique event ID
const eventId = `purchase_${orderId}_${Date.now()}`;

// Send via browser pixel
ttq.track('CompletePayment', {
  value: 89.99,
  currency: 'USD',
  content_type: 'product'
}, { event_id: eventId });

Server-side (Events API):

# Use the same event_id from the browser
send_tiktok_event(
    event_name="CompletePayment",
    event_id="purchase_12345_1679094000000",  # Same ID as browser
    # ... other params
)

TikTok automatically deduplicates events with the same event_id within a 48-hour window.

Step 6: Verify in TikTok Events Manager

1. Go to TikTok Ads Manager → Assets → Events
2. Click on your pixel
3. Check the Overview tab for incoming events
4. Look for events labeled as Web (Server) — these are your Events API events
5. Click Diagnostics to check match rates and data quality

---

Setup Method 2: TikTok's Integrations (Shopify, GTM)

TikTok offers native integrations with popular platforms that simplify the setup.

Shopify Integration

1. Install the TikTok app from the Shopify App Store
2. Connect your TikTok for Business account
3. The app automatically sets up both the Pixel and Events API
4. Events are sent server-side through Shopify's servers

Limitations:

• Limited customization of event parameters
• No bot filtering or data quality controls
• Tied to Shopify's implementation timeline for updates

Google Tag Manager (Server-Side GTM)

1. Set up a server-side GTM container (requires Google Cloud)
2. Install the TikTok tag template in your server container
3. Configure event triggers and user data variables
4. Route browser events through your server GTM before sending to TikTok

Limitations:

• Requires server-side GTM infrastructure ($50-200+/mo)
• Complex setup and ongoing maintenance
• No built-in deduplication or bot filtering

---

Setup Method 3: Automated with SignalBridge (Recommended)

The manual methods work but require significant developer time, infrastructure, and ongoing maintenance. SignalBridge automates the entire process.

How it works:

1. Connect TikTok — Click "Connect with TikTok" in your SignalBridge dashboard. Authorize via OAuth (one click — no manual token generation)
2. Select your pixel — SignalBridge auto-discovers your TikTok pixels and lets you select from a dropdown
3. Done — SignalBridge automatically captures conversions server-side, hashes user data, and sends events to TikTok's Events API

What SignalBridge handles automatically:

Setup time comparison:

---

TikTok Events API Standard Events

TikTok defines a set of standard events for e-commerce. Use these event names for best optimization:

Important: CompletePayment is TikTok's primary optimization event for e-commerce. Always include value and currency to enable Value-Based Optimization (VBO).

---

Maximizing Match Quality

Match quality measures how well TikTok can attribute your server-side events to ad interactions. Higher match quality = better ad optimization.

How to improve match quality:

1. Always pass ttclid — This is the highest-quality signal. It directly connects the conversion to the ad click. Capture it on landing and persist it through the session.

2. Include hashed email — Most TikTok users have an account linked to their email. Hashing with SHA-256 and normalizing (lowercase, trim whitespace) before hashing is critical.

3. Include hashed phone number — Secondary matching signal. Normalize to E.164 format before hashing.

4. Send IP address and user agent — These help TikTok match events when ttclid is unavailable. Send the user's original IP and user agent (not your server's).

5. Minimize event delivery latency — Send events within seconds of the conversion, not hours or days later. Real-time delivery improves match accuracy.

6. Use consistent event IDs — When running both Pixel and Events API, the same event_id enables deduplication and prevents double-counting that distorts your data.

Match quality scoring:

---

Common Issues and Troubleshooting

"No permission to operate event source"

Cause: Your access token doesn't have the "Report Pixel Event" permission. Fix: In the TikTok Developer Portal, go to your app → Scope of Permission → enable Measurement → Report Pixel Event. If the permission requires approval, submit a request with your use case.

Events not appearing in Events Manager

Cause: Pixel code mismatch, incorrect API endpoint, or token issues. Fix:

1. Verify you're using the correct pixel code (check TikTok Ads Manager → Assets → Events)
2. Confirm the API endpoint: https://business-api.tiktok.com/open_api/v2/pixel/track/
3. Check that your access token is valid and not expired (24-hour expiry)

Low match rate

Cause: Missing user identifiers or incorrect hashing. Fix:

1. Always include ttclid when available (highest match quality)
2. Hash email and phone with SHA-256 after normalizing (lowercase, trim)
3. Include IP address and user agent from the original request
4. Send events in real-time, not batched hours later

Duplicate events in reporting

Cause: Both Pixel and Events API sending the same event without deduplication. Fix: Use the same event_id value in both the browser Pixel call and the server API call. TikTok deduplicates within a 48-hour window.

Access token expired

Cause: TikTok access tokens expire every 24 hours. Fix: Implement automatic token refresh using the refresh token (valid for 365 days). Tools like SignalBridge handle this automatically.

---

FAQ

Do I still need the TikTok Pixel if I use Events API?

Yes, TikTok recommends running both together. The browser Pixel provides real-time signals for dynamic ads and audience building, while Events API catches the 20-40% of events the Pixel misses. Together with event deduplication, you get the most complete picture.

How is TikTok Events API different from Meta CAPI?

They solve the same problem — server-side conversion tracking — but differ in implementation details. TikTok uses 24-hour access tokens with 365-day refresh tokens; Meta uses ~60-day long-lived tokens. Both accept SHA-256 hashed user data. Both recommend running alongside their browser pixel with event deduplication.

What programming language do I need for Events API?

TikTok Events API is a REST API that accepts JSON over HTTPS. You can implement it in any server-side language — Python, Node.js, PHP, Ruby, Java, Go, etc. Or use a tool like SignalBridge that handles the implementation for you.

How much does it cost to use TikTok Events API?

The Events API itself is free. TikTok doesn't charge for receiving server-side events. Your costs are infrastructure (server to send events) and development time (building and maintaining the integration). Tools like SignalBridge start at $29/mo and handle all the infrastructure.

Can I use Events API with a sandbox / test account?

TikTok provides a sandbox environment for testing. However, sandbox accounts have limitations on advertiser approval and campaign creation. For production testing, you'll need an approved advertiser account. You can start with test events and verify they appear in Events Manager before going live.

Does Events API work with TikTok Shop?

TikTok Shop has its own integrated tracking. Events API is designed for external websites (your Shopify store, custom site, etc.) where TikTok ads drive traffic. If you sell both on TikTok Shop and your own website, Events API handles the website conversions.

---

Related Reading

• What is Facebook Conversions API (CAPI)? — Meta's equivalent server-side tracking solution
• How to Set Up Google Enhanced Conversions — Google's server-side tracking implementation
• What is Server-Side Tracking? — the broader concept behind Events API, CAPI, and Enhanced Conversions
• How to Fix iOS Tracking Issues — the privacy changes that make server-side tracking necessary
• Complete Guide to Event Match Quality — maximizing data quality for better ad optimization

---

Ready to Set Up TikTok Events API?

Skip the manual tokens, API code, and maintenance headaches. SignalBridge sets up TikTok Events API, Meta CAPI, and Google Enhanced Conversions with a single one-click integration. Recover lost conversions, improve ad optimization, and see your true ROAS — all from one dashboard.

Start your 14-day free trial today. No credit card required.