To set up the TikTok Pixel, open TikTok Ads Manager, go to Tools > Events, click Connect Data Source, choose Web, name your pixel, then install it either manually in your site’s head, through a partner integration like Shopify, or with Google Tag Manager. After that you configure standard events and verify them in Test Events.
</head> tag on every page, or let a partner integration do it. 3. Add standard events such as ViewContent, AddToCart and CompletePayment with value and currency. 4. Verify with the TikTok Pixel Helper extension and Test Events, then mark your money event as the optimization event on your campaigns.One naming note before you start, because TikTok’s own docs are inconsistent. TikTok Pixel is the browser-side JavaScript tag. Events API (currently version 2.0) is the server-side equivalent. Both feed the same data source in Events Manager, and TikTok recommends running them together rather than choosing one. You will also see friendly event labels in the interface (“Add to Cart”, “Purchase”) that differ from the code-level names you type in JavaScript. I’ve listed both below.
Step 1: Create the pixel in TikTok Events Manager
- Log in to TikTok Ads Manager and open Tools > Events.
- Click Connect Data Source and choose Web.
- Name the pixel something you will recognize in six months. Every event sent to this pixel code will be grouped under this name, so use the domain rather than “Pixel 1”.
- Choose your connection method: Partner Integration or Manual Setup.
- Copy the pixel ID. You will need it for GTM or a plugin.
You get one Events Manager workspace per ad account, and inside it the Overview, Test events, Diagnostics, Change log and Settings sections. Bookmark Diagnostics now, because it is where TikTok tells you what’s broken.
Step 2: Pick an install method
| Method | Best for | Effort | Trade-off |
|---|---|---|---|
| Manual code | Custom sites, full control over event timing | High | Every change needs a developer. Easy to break on theme updates. |
| Google Tag Manager | Anyone already running GTM, multiple pixels | Medium | One more layer to debug, but easily the most maintainable. |
| Partner integration (Shopify, WooCommerce) | Ecommerce stores on a supported platform | Low | Fastest and sends product data automatically, but you inherit whatever events the app decides to fire. |
My recommendation: if you run Shopify or WooCommerce, use the official TikTok app or plugin and stop there. It wires up product IDs, values and currency for you, which is the part people get wrong by hand. If you have a custom site or already manage tags centrally, use GTM. There’s a walkthrough for the WordPress side in our guide to installing Google Tag Manager on WordPress, and TikTok publishes an official GTM community template you can import instead of writing custom HTML tags.
Step 3: Where the base code goes
The base code belongs in the <head> of every page, as high as practical and before the closing </head> tag. Copy it from Events Manager rather than from a blog post, because it embeds your pixel ID. The tail of the snippet is what matters for troubleshooting:
<!-- End of the TikTok base code, after the loader -->
ttq.load('YOUR_PIXEL_ID');
ttq.page();ttq.load() initializes the pixel and ttq.page() fires the page view. If Pixel Helper reports the pixel but no Pageview, one of those two lines is missing or running before the loader finished.
Step 4: Configure standard events
Standard events are the named actions TikTok’s optimization models understand. Custom events work but get less algorithmic help, so map to a standard event wherever you honestly can.
| Code-level name | Interface label | Fires when |
|---|---|---|
| ViewContent | View Content | A visitor views a page that matters, typically a product page |
| ClickButton | Click Button | A visitor clicks a tracked button or element |
| Search | Search | A visitor runs a site search |
| AddToWishlist | Add to Wishlist | An item is added to a wishlist |
| AddToCart | Add to Cart | An item is added to the cart |
| InitiateCheckout | Initiate Checkout | A visitor proceeds to checkout |
| AddPaymentInfo | Add Payment Info | Payment details are entered at checkout |
| CompletePayment | Purchase | The purchase completes. This is your money event. |
| PlaceAnOrder | Place an Order | An order is placed. Skip it if ordering and paying are the same step. |
| SubmitForm | Submit Form | A form is submitted. The default lead-gen event. |
| CompleteRegistration | Complete Registration | An account is created |
| Contact | Contact | A visitor contacts you by phone, chat or email |
| Download | Download | A file is downloaded |
| Subscribe | Subscribe | A follow, content or paid subscription starts |
TikTok has also added newer objective-specific events in the interface, including Start Trial, Schedule, Submit Application and Application Approval, which are useful for finance, education and services advertisers. Check the current supported standard events page before you build, because this list grows.
Standard Mode: click and URL rules, no code
Standard Mode uses the Event Builder, which supports two rule types. Button Clicks measures when a specific button or element is clicked, selected visually on your live site. URL Visits measures when a URL containing a keyword is visited.
So a typical lead-gen setup becomes: SubmitForm on a URL Visit rule matching /thank-you, and ViewContent on a URL Visit rule matching /services/. It takes five minutes and needs no developer. The limitation is real though: URL rules cannot pass a dynamic order value, so ROAS optimization is off the table.
Developer Mode: code, and the only way to pass real values
Developer Mode means you call ttq.track() yourself. This is what you want on any store where the order total varies.
// Product page view
ttq.track('ViewContent', {
contents: [{
content_id: 'SKU-4417',
content_type: 'product',
content_name: 'Trail Runner 3',
price: 129.00,
quantity: 1
}],
value: 129.00,
currency: 'USD'
});
// Order confirmation page
ttq.track('CompletePayment', {
contents: [
{ content_id: 'SKU-4417', content_type: 'product', price: 129.00, quantity: 1 },
{ content_id: 'SKU-2210', content_type: 'product', price: 24.00, quantity: 2 }
],
value: 177.00,
currency: 'USD'
});Value and currency: the two parameters that decide whether optimization works
value is the total for the whole event, while price is the unit price of a single item inside contents. Mixing these up is the most common cause of ROAS numbers that are wrong by an order of magnitude.
TikTok’s own requirements are specific: currency as an ISO 4217 code is required for ROAS reporting, and content_type set to product or product_group is required for Video Shopping Ads. USD is supported alongside roughly 60 other currencies. Send the number as a number, not a string with a dollar sign, and exclude shipping and tax unless you genuinely want to optimize toward them.
Advanced Matching and the hashed-email requirement
Advanced Matching sends hashed customer identifiers with the event so TikTok can attribute conversions it would otherwise miss when cookies are unavailable. Three fields are supported: email, phone number, and an external ID of your own.
You have two options, and the distinction matters:
- Pass plain values in
email,phone_numberandexternal_id, and the pixel hashes them in the browser before transmission. - Hash them yourself with SHA-256 and pass
sha256_emailandsha256_phone_number. The external ID key staysexternal_ideither way.
// Call identify before track, once you know who the user is.
// Lowercase and trim the email; format the phone in E.164.
ttq.identify({
email: 'buyer@example.com',
phone_number: '+14155551234',
external_id: 'customer_98213'
});
ttq.track('CompletePayment', { value: 177.00, currency: 'USD' });ttq.identify() before the visitor has consented. Advanced Matching is personal data processing, and if you serve visitors in the EU, the UK, California or a growing list of other US states, your consent banner has to gate it.Test it before you spend a dollar
Two tools, use both.
TikTok Pixel Helper is a Chrome extension. Install it, load your site, and it lists the pixels found, the events fired, and the parameters attached to each. It flags missing required parameters, which is the fastest way to catch a CompletePayment with no value.
Test Events lives inside Events Manager and filters between browser-side (Pixel) and server-side (Events API) traffic. Enter your site URL, complete a real journey, and watch events land in real time. This is the one that proves the data actually reached TikTok, not just that the JavaScript ran.
Then check Diagnostics. It surfaces setup problems with severity, affected datasets and fix instructions, including missing parameters, missing content IDs, and a first-party cookie that hasn’t been enabled.
Turn the event into a conversion for campaign optimization
A firing pixel does not optimize anything on its own. When you build a campaign, choose the Website conversions objective, select your pixel, then select the specific optimization event, normally CompletePayment for ecommerce or SubmitForm for lead generation.
Pick an event that fires often enough to train on. Optimizing toward an event that happens twice a week gives the algorithm almost nothing to work with. If your purchase volume is low, optimize toward InitiateCheckout or AddToCart first and move down the funnel once volume supports it. The same logic applies to key events in GA4, which we cover in using Google Analytics for marketing.
Add the Events API for server-side tracking
Browser-based pixels lose data, and not a small amount. Apple’s App Tracking Transparency and Intelligent Tracking Prevention limit what a third-party script can persist, ad blockers strip the request entirely, and a consent banner legitimately blocks it for a share of visitors. On mobile-heavy traffic like TikTok’s, that adds up fast.
The Events API (2.0) sends events from your server directly to TikTok, so it survives all three. You have three ways in: a commerce partner such as Shopify or WooCommerce, a data partner such as a CDP or server-side tag manager, or a direct integration with an access token from the developers portal. TikTok explicitly recommends running the Events API as a second channel alongside the pixel rather than replacing it, because the pixel still contributes browser-side signals the server cannot see.
event_id from the pixel and the Events API for the same action. TikTok matches on event_id plus event name and keeps the first event it received. The window is 48 hours from the first event, and for pixel-to-Events-API overlap TikTok waits at least 5 minutes before deduplicating. Without a shared event_id, TikTok cannot tell duplicates apart at all.Troubleshooting
The pixel shows “inactive”
Inactive means TikTok has not received an event recently, not that the code is wrong. Load a page yourself and check Pixel Helper. If the extension sees nothing, the base code is missing on that template, was pasted below </head>, is being stripped by a caching or optimization plugin that defers scripts, or the pixel ID in ttq.load() belongs to a different pixel. A brand-new pixel also reads inactive until the first event arrives, so send one.
Events fire twice
Almost always a plugin and manual code both installed. The classic version is the official Shopify or WooCommerce TikTok app plus a hand-pasted base code in the theme header, so every event fires from two sources. Remove one. Pixel Helper will show you two identical events with the same parameters, which is the tell. The other cause is a single-page app calling ttq.page() on both initial load and the first route change.
No conversions attributed to your ads
Work through it in order. Is the event actually reaching TikTok, per Test Events? Is that event selected as the optimization event on the ad group? Is the pixel shared with the right ad account, if it lives in a Business Center? Has enough time passed for the attribution window? And is Advanced Matching enabled? Without it, attribution on iOS traffic drops noticeably. A pixel that records events but attributes none is usually a pixel that isn’t linked to the campaign, not a broken pixel.
A consent banner is blocking the pixel
This is working as designed, and you should not disable it. What you can do is make sure the banner does not block the pixel for visitors who did consent, which is a common misconfiguration when the banner defers all third-party scripts by category. In GTM, gate the TikTok tag on a consent-granted trigger rather than blocking the whole container. And accept a permanent gap between TikTok’s reported conversions and your own order count, for the same reasons GA4 and ad platforms never agree.
Frequently asked questions
How long does it take for the TikTok Pixel to become active?
It flips to active as soon as the first event reaches TikTok, usually within minutes of a real page load. If it still reads inactive after 20 minutes of you browsing your own site, the base code is not firing rather than being slow. Check Pixel Helper first, then Diagnostics.
Do I need both the TikTok Pixel and the Events API?
For anything with real budget behind it, yes. TikTok recommends the Events API as a second channel alongside the pixel, not a replacement. The pixel captures browser signals, the API survives ad blockers and iOS restrictions. Just share an event_id between them so TikTok can deduplicate.
Can I install the TikTok Pixel with Google Tag Manager?
Yes, and it’s the option I’d pick for most non-Shopify sites. TikTok maintains an official GTM community template, so you configure the pixel ID, event name and parameters in a form instead of writing a custom HTML tag. It also makes consent gating far simpler.
What is the difference between value and price in TikTok events?
value is the total for the whole event, such as the full order amount. price is the unit price of one item inside the contents array. Send both on purchase events, and always pair value with an ISO 4217 currency code or ROAS will not calculate.
Is it still safe to advertise on TikTok in the US?
The platform is operating normally. The US joint venture, TikTok USDS Joint Venture LLC, was established in January 2026 with Oracle, Silver Lake and MGX as managing investors, and advertising operations continue as before. Sensible advertisers diversify across platforms regardless, but there is no current pixel or Ads Manager disruption to plan around.
Wrapping up
The honest shortest path: create the pixel, install it through a partner integration if your platform supports one, configure ViewContent, AddToCart, InitiateCheckout and CompletePayment with real values and currency, turn on Advanced Matching behind your consent banner, and verify in Test Events before your first campaign goes live. That is a one-afternoon job and it covers 90% of what TikTok’s optimization needs.
Add the Events API once you’re spending enough that a 20% data loss costs real money, and remember the shared event_id. If you’re also measuring the same conversions in Google Analytics, it’s worth reading how to track a custom event in Google Analytics 4 so your event naming stays consistent across platforms. TikTok’s own Set up and Verify Pixel guide is the reference to keep open, and the event deduplication article is worth reading twice before you go server-side.
