TikTok Pixel & Events API Setup Guide: Track Conversions the Right Way

The TikTok Pixel and Events API are how TikTok learns which ads drive sales, leads and sign-ups on your website. Without them, you cannot run Web Conversions campaigns, optimize for purchases or build retargeting audiences. TikTok recommends using both together: the Pixel in the browser and the Events API from your server, with duplicate events removed. This guide shows you how to set up each part, which events to track, and how to check that everything works.

What are the TikTok Pixel and Events API?

The TikTok Pixel is a piece of JavaScript code on your website that reports what visitors do, such as viewing a product or completing a purchase. The Events API is a server-to-server connection that sends the same kind of event data directly from your server, CRM or app to TikTok.

According to TikTok's About Events API page, a Pixel or Events API setup is a prerequisite for the Web Conversions objective, and TikTok recommends adding the Events API to an existing Pixel for website connections.

Why you need both

The Pixel alone misses conversions. Ad blockers, browser privacy settings, slow pages and users who close the tab before the thank-you page loads all stop browser events from reaching TikTok. The Events API fills those gaps because it does not depend on the visitor's browser.

More complete data matters for three reasons:

• Optimization: TikTok's delivery system learns from conversions. Fewer reported conversions means slower learning and a higher cost per result. See how this affects the TikTok learning phase.

• Measurement: your reporting in Ads Manager is closer to what your backend shows. Reliable tracking is one of the core web ads success factors.

• Audiences: retargeting and lookalike audiences are built from the events you send.

Step 1: Create your TikTok Pixel

You create the Pixel in TikTok Ads Manager:

1. Go to Tools > Events Manager and choose Web events (connect data source).

2. Name your Pixel, ideally after your website or brand.

3. Choose how to connect: a partner platform (Shopify, WooCommerce and others), manual installation of the code, or Google Tag Manager.

4. Turn on Advanced Matching if your privacy policy allows it. It sends hashed email and phone data to improve conversion matching and audience size.

If your store runs on a supported e-commerce platform, use the partner integration. It installs the Pixel, sets up standard events and, on many platforms, turns on the Events API automatically.

Step 2: Install the Pixel base code

The base code must load on every page of your site, including checkout and thank-you pages. A common mistake is installing it on the main domain while checkout runs on a different domain or subdomain, which means purchases are never reported.

• Manual install: paste the base code into the <head> of your site template.

• Google Tag Manager: add the TikTok Pixel template and fire it on all pages.

• Partner platform: connect your store account and follow the setup wizard.

If you send traffic to a fast in-app page instead of your website, a TikTok Instant Page does not need a Pixel for on-page tracking.

Step 3: Choose the right standard events

Standard events are the predefined actions TikTok uses for reporting, optimization and audiences. In 2025 TikTok renamed two key events: SubmitForm became Lead and CompletePayment became Purchase. TikTok's standard events update says new setups should use the new names, while legacy names keep working. ClickButton and PlaceAnOrder are being phased out and are scheduled to retire in 2027.

Always send value and currency with Purchase events, and content_ids for products. These parameters power value-based optimization and catalog ads.

Example Pixel event with an event ID:

ttq.track('Purchase', {
  contents: [{ content_id: 'SKU123', content_type: 'product', quantity: 1, price: 29.99 }],
  value: 29.99,
  currency: 'USD'
}, { event_id: 'order_10045' });

ttq.track('Purchase', {
  contents: [{ content_id: 'SKU123', content_type: 'product', quantity: 1, price: 29.99 }],
  value: 29.99,
  currency: 'USD'
}, { event_id: 'order_10045' });

ttq.track('Purchase', {
  contents: [{ content_id: 'SKU123', content_type: 'product', quantity: 1, price: 29.99 }],
  value: 29.99,
  currency: 'USD'
}, { event_id: 'order_10045' });

Step 4: Set up the Events API

There are three ways to connect the Events API, from easiest to most flexible:

• Partner integration: many e-commerce platforms and tag tools include the Events API in their TikTok integration. Turn it on during setup.

• Events API Gateway: TikTok's tool for creating a server-to-server connection quickly and managing multiple ad accounts from one host, according to TikTok's Events API Gateway page. Useful for agencies and multi-brand businesses.

• Direct API integration: your developers send events from your server. Generate an access token in Events Manager, then post events to TikTok's Events API endpoint.

A simplified direct API payload looks like this:

{
  "event_source": "web",
  "event_source_id": "YOUR_PIXEL_ID",
  "data": [{
    "event": "Purchase",
    "event_time": 1761045600,
    "event_id": "order_10045",
    "user": { "email": "<sha256-hashed>", "phone": "<sha256-hashed>", "ttclid": "...", "ip": "...", "user_agent": "..." },
    "properties": { "currency": "USD", "value": 29.99 },
    "page": { "url": "https://example.com/thank-you" }
  }]
}

{
  "event_source": "web",
  "event_source_id": "YOUR_PIXEL_ID",
  "data": [{
    "event": "Purchase",
    "event_time": 1761045600,
    "event_id": "order_10045",
    "user": { "email": "<sha256-hashed>", "phone": "<sha256-hashed>", "ttclid": "...", "ip": "...", "user_agent": "..." },
    "properties": { "currency": "USD", "value": 29.99 },
    "page": { "url": "https://example.com/thank-you" }
  }]
}

{
  "event_source": "web",
  "event_source_id": "YOUR_PIXEL_ID",
  "data": [{
    "event": "Purchase",
    "event_time": 1761045600,
    "event_id": "order_10045",
    "user": { "email": "<sha256-hashed>", "phone": "<sha256-hashed>", "ttclid": "...", "ip": "...", "user_agent": "..." },
    "properties": { "currency": "USD", "value": 29.99 },
    "page": { "url": "https://example.com/thank-you" }
  }]
}

Check TikTok's Events API developer documentation for the current endpoint version and required fields before going live.

Step 5: Deduplicate Pixel and Events API events

If you send the same event through both the Pixel and the Events API, you must deduplicate it, or one purchase will be counted twice. TikTok's event deduplication rules require the same event name and the same event_id in both copies.

• Use a stable, unique ID for each conversion, such as the order ID or lead ID.

• Generate it once and pass it to both the browser and the server.

• TikTok deduplicates matching events that arrive within a 48-hour window. When a Pixel event and an Events API event match, TikTok merges or deduplicates them and keeps the first event received for reporting.

Deduplication is not needed if you send different events through each channel, for example AddToCart through the Pixel and Purchase through the Events API.

Step 6: Verify your setup

Check your data before you launch campaigns, not after:

• Events Manager: open your Pixel and confirm each event is receiving activity, with no errors in diagnostics.

• Test Events: use the test tool in Events Manager to trigger events from your own browser and server and see them arrive.

• TikTok Pixel Helper: the Chrome extension shows which Pixel events fire on each page.

• Compare with your backend: reported purchases in TikTok should be close to (not double) your actual orders.

Common TikTok Pixel and Events API mistakes

Most tracking problems come from a few setup errors:

• Pixel missing on the checkout domain, so purchases never fire.

• Different event_ids in the Pixel and Events API, so purchases are double-counted.

• Purchase fired on page load of the cart or checkout instead of after payment succeeds.

• No value or currency, which blocks value-based optimization and ROAS reporting.

• Unhashed personal data sent through the Events API. Email and phone must be SHA-256 hashed.

• Several Pixels on one site firing the same events.

FAQ

1. Do I need the Events API if I already have the TikTok Pixel?

   It is strongly recommended. TikTok advises pairing the Events API with an existing Pixel for website connections, because the server connection captures conversions the browser misses.

2. What is the difference between CompletePayment and Purchase?

   They are the same event. TikTok renamed CompletePayment to Purchase in 2025; existing setups keep working, but new setups should use Purchase.

3. How does TikTok deduplicate events?

   It matches events with the same event name and event_id. Send the same event_id, such as your order ID, through both the Pixel and the Events API.

4. Can I run TikTok ads without a Pixel?

   Yes, for objectives like reach, video views, Instant Form lead generation or TikTok Shop ads. Web Conversions campaigns require a Pixel or Events API setup.

5. How long until new events can be used for optimization?

   Events appear in Events Manager within minutes of firing. Campaigns still need enough conversions to exit learning, so send clean data before scaling.

Get accurate TikTok tracking from day one

A clean Pixel and Events API setup gives TikTok's algorithm the data it needs to find buyers, and gives you reporting you can trust. Install the Pixel on every page, use the updated standard events, add the Events API with a shared event_id, and verify before you spend. If you are launching your first campaigns, our TikTok Ads beginner's guide walks through the rest of the setup.

Ecomdy is an official TikTok agency. If you want help auditing your Pixel and Events API setup or opening a TikTok agency ad account, contact the Ecomdy team.