PostHog TikTok Ads Integration: Conversion Tracking

Send leads and purchases from PostHog to TikTok with matching event IDs, customer details, and accurate order values. Check the response before enabling live traffic.

Part of Send PostHog conversions to Meta, Google Ads, TikTok and more.

The TikTok logo on a dark tile at lower left is tied to a conversion ticket with the PostHog mark at upper right by a thick cord braided from four strands. Near the start the strands run apart under tags: ttclid (blue), email, and IP + UA on a twisted grey pair. Above, a single thin thread between the same two points has frayed apart in the middle.

To send purchases, leads, and other PostHog conversions to TikTok, use the TikTok Ads Conversions destination. Connect the TikTok Pixel ID and access token, then create a mapping for each conversion you want to report. (+)

This guide follows the destination form, including the defaults to change before enabling it. For the prerequisites shared by all six platforms, start with our overview of PostHog’s ad destinations.

Requirements

Before you begin, install and configure PostHog to capture the conversion events you want to send to TikTok Ads. If capture is not in place yet, install PostHog first.

Choose the source event by what it proves: a purchase event should mean payment completed, not that someone opened a thank-you page. Record the event’s meaning, original time, conversion ID, order total (including whether it contains tax and shipping) and currency in your event tracking plan.

You’ll also need access to the relevant TikTok ad account and to any browser Pixel integration already reporting the same conversions. That lets you coordinate the browser and server event IDs before adding another sender.

Set up the TikTok Ads Conversions destination

To get started, open Destinations in PostHog and click New destination. Search for TikTok Ads Conversions and click + Create. (+ / +)

PostHog Destinations screen showing the TikTok Ads Conversions destination search result
The destination chooser shows the TikTok template with its Experimental label. The following tables correct the template’s defaults.

The template is alpha, shown as Experimental, and PostHog does not provide official customer support for it. Allow for template changes and verify delivery in your own setup. (+ / +)

Use one destination with a mapping for each conversion action. (+) Use separate destinations when credentials, consent rules or ownership differ.

Connect your TikTok Ads account

Next, connect your TikTok Ads account to PostHog. For this step, you’ll need two values: your Pixel ID, which tells PostHog where to send events, and your access token, which authorizes PostHog to connect to TikTok Ads.

In TikTok Ads Manager, go to Tools → Events → Data sources and open your pixel. Its Pixel Code is the value to use for Pixel ID. (+)

In Events Manager, open that pixel’s Settings tab and click Generate Access Token. You must be an Admin or Operator on the ad account; this token can send events only for pixels under the same ad account. (+)

Paste both values into PostHog’s destination fields. Use the same Pixel ID as the browser Pixel when both report the same website conversions. (+)

TikTok Ads Conversions destination setup fields for an access token and Pixel ID
The template’s default credential form, with Pixel ID and secret Access token inputs. Follow the Events Manager steps above to obtain them.

Common fields

User properties

Map the matching fields available for your conversion events.

TikTok’s matching works best when you send multiple reliable identifiers instead of relying on a single field. Advanced Matching fields, ttclid, cookies, IP address and user agent provide different ways to connect a conversion to a person. (+)

TikTok Ads Conversions user-property mappings in PostHog
User properties prefilled by the template. The table below shows which defaults to keep and which to replace.

Matching fields

The template sends mapped user values without further normalization and keeps empty strings, so use null for unknown optional fields. Hash only the fields TikTok requires, once, after preparing the required format. (+ / +)

FieldPostHog’s defaultWhat to change and why
ttclid{person.properties.ttclid ?? person.properties.$initial_ttclid}The default reads the latest person value, then the first-ever value. That fallback may predate this visit. Preserve the latest genuine click ID tied to the conversion and send it on each event where it is available. Never truncate it; TikTok allows up to 1,000 characters. (+)
email{not empty(person.properties.email) ? sha256Hex(lower(person.properties.email)) : ''}Trim, lowercase, then SHA-256 hash. The default misses trimming. Use {not empty(trim(person.properties.email ?? '')) ? sha256Hex(lower(trim(person.properties.email))) : null}.
phone{not empty(person.properties.phone) ? sha256Hex(person.properties.phone) : ''}Normalize upstream to E.164, keeping the leading + and country code. Store that validated string as phone_e164 and use {not empty(person.properties.phone_e164) ? sha256Hex(person.properties.phone_e164) : null}. The default hashes the raw value.
external_id{not empty(person.id) ? sha256Hex(person.id) : ''}The default hashes PostHog’s person UUID. Use your own stable customer ID, hashed consistently wherever TikTok receives it: {not empty(person.properties.customer_id) ? sha256Hex(toString(person.properties.customer_id)) : null}.
ttpNo default.Add the raw _ttp cookie value as ttp. For the capture example below, map {event.properties.ttp}.
ip{event.properties.$ip}Keep the visitor’s public IP unhashed. For backend events, supply the visitor’s IP explicitly; see the browser-context section below.
user_agent{event.properties.$raw_user_agent}Keep the browser’s user agent unhashed. This event default is right for browser captures; backend captures need retained visitor context.

With campaign capture enabled, posthog-js captures ttclid from the landing URL; identified profiles can hold the latest ttclid and the first-touch $initial_ttclid. It does not read the _ttp cookie. If mask_personal_data_properties is on, the captured value becomes <masked>, which the default mapping would forward. (+ / +) This expression reads the event first and the person second, and leaves the field out when the value is blank or that placeholder:

{not empty(event.properties.ttclid ?? '') ? (event.properties.ttclid == '<masked>' ? null : event.properties.ttclid) : (not empty(person.properties.ttclid ?? '') and person.properties.ttclid != '<masked>' ? person.properties.ttclid : null)}

Our ad URL guide explains capture and what can be lost between the landing and conversion.

When available, ttclid helps TikTok connect the conversion directly to the originating ad interaction.

Normalize phone numbers before they reach this form. A general string replacement cannot validate a country code or turn a local number into E.164. The phone_e164 and customer_id properties above are example property names; create them in your own capture or person data.

Set person-based matching data before the conversion is processed. A later identify() call does not add it to an event that has already triggered the destination. Alternatively, include matching data on the conversion event and change these expressions to read event.properties. (+)

Browser context for backend conversions

Send ip and user_agent together, in their original, unhashed form. For a browser event, use the event defaults above. A backend capture does not inherit the visitor’s browser context: without an explicit visitor IP, $ip falls back to the capture request’s IP, which can be your server’s. (+)

For a backend conversion, {person.properties.$raw_user_agent} can use a previously captured browser value on an identified profile. PostHog copies browser user-agent data onto person profiles, but does not automatically copy $ip there. Check that both values belong to the visitor whose conversion you are sending; our visitor IP guide covers retaining that context.

If Discard client IP data is enabled, $ip is removed from stored events. Treat that as a collection choice to respect when configuring advertising exports. (+)

When the Pixel’s first-party cookies are enabled, its _ttp cookie helps TikTok match website visitors. Send that cookie value unchanged as user.ttp. (+) Add a ttp key under User properties, using the capture example below.

This example reads the cookie only when your consent tool’s current adsConsent boolean is true. Include ttp and ads_consent on your existing conversion event, setting ads_consent to the same adsConsent value:

const ttp = adsConsent === true
  ? document.cookie.split(';').map(part => part.trim())
      .find(part => part.startsWith('_ttp='))?.slice(5) || undefined
  : undefined

Optional location and name fields

The location defaults use GeoIP, which locates an IP address; they do not verify the customer’s postal address. (+) Remove fields whose source or normalization you cannot establish. Prepare address and name formats upstream, then hash the fields that require it. (+)

FieldPostHog’s defaultWhat to change and why
city{not empty(person.properties.$geoip_city_name) ? replaceAll(lower(person.properties.$geoip_city_name), ' ', '') : null}This is IP-derived location. For a customer-address city, normalize an actual address upstream: lowercase, with no spaces, punctuation or special characters. The default only removes spaces.
state{lower(person.properties.$geoip_subdivision_1_code)}This sends an IP-derived subdivision code. TikTok wants a lowercase two-letter code for US states, but outside the US a state or province name in lowercase, with spaces, punctuation and special characters removed.
country{lower(person.properties.$geoip_country_code)}This is the IP-derived country, not a verified customer address. An address country uses a lowercase two-letter ISO 3166-1 code.
zip_code{not empty (person.properties.$geoip_postal_code) ? sha256Hex(replaceAll(lower(person.properties.$geoip_postal_code), ' ', '')) : null}For an actual address, lowercase, remove spaces and dashes, use only the first five digits for a US ZIP, then hash with SHA-256. The default removes spaces but keeps dashes.
first_name{not empty(person.properties.first_name) ? sha256Hex(lower(person.properties.first_name)) : ''}Trim and lowercase, remove punctuation, then hash with SHA-256. Preserve permitted special characters. The default does not complete that normalization.
last_name{not empty(person.properties.last_name) ? sha256Hex(lower(person.properties.last_name)) : ''}Apply the same normalization and hashing rule as first name.

Event-specific fields

The destination sends website conversions: its code fixes event_source: 'web'. A new destination starts with eleven mappings and prefilled fields for each. A backend payment can represent a website purchase, but it still needs the website’s page and visitor context. (+)

Mappings

PostHog provides a default mapping template to help you get started, but it should be adjusted to reflect your own event structure and conversion logic.

Match events and actions: Choose the PostHog event that best matches the conversion action you want to send to TikTok Ads. For example, if you want to send a Purchase event, map it to the PostHog event that represents a completed order or successful transaction. When needed, you can include multiple PostHog events in the same mapping.

TikTok Ads Conversions mapping in PostHog showing Pageview mapped to Page Viewed
The template’s Page Viewed mapping, including its default Event ID and timestamp. Remove this mapping and correct the conversion fields below.

Remove the mappings you do not need, and correct these names before enabling production traffic:

Default mappingChange
Page Viewed → PageviewRemove it. Pageview is not a standard web event, and a browser Pixel already sends page views from its base code. (+)
Order Completed → CompletePaymentUse Purchase for completed payments and match the name on the browser side.
Product Clicked → ClickButtonRemove it or choose an event that describes the action. Use ViewContent only when content was actually viewed.
Order Placed → PlaceAnOrderRemove it or replace it with the appropriate current event. Avoid an extra purchase report for an order already covered by Purchase.
No lead mappingAdd a Lead mapping if you send form submissions.

CompletePayment became Purchase and SubmitForm became Lead for web events on 1 May 2025. Those legacy names remain supported indefinitely. ClickButton and PlaceAnOrder are soft-deprecated and sunset in 2027, so choose current names for new setups. (+) Avoid emitting two differently named purchase events for the same order merely to cover both taxonomies.

Event name: TikTok supports eighteen standard web events. Use their exact, case-sensitive API names:

Add Payment Info (AddPaymentInfo), Add to Cart (AddToCart), Add to Wishlist (AddToWishlist), Application Approval (ApplicationApproval), Purchase (Purchase), Complete Registration (CompleteRegistration), Contact (Contact), Customize Product (CustomizeProduct), Download (Download), Find Location (FindLocation), Initiate Checkout (InitiateCheckout), Lead (Lead), Schedule (Schedule), Search (Search), Start Trial (StartTrial), Submit Application (SubmitApplication), Subscribe (Subscribe), and View Content (ViewContent). (+)

You can also send custom web events by entering a custom event name. TikTok reports them and lets you build audiences from them, but they cannot be used for campaign optimization. (+)

A subscription-app example

In a subscription-app implementation, we used separate mappings for signup, checkout or plan selection, trial and purchase. For website conversions, the pattern is:

ActionTikTok eventConversion-level ID
Signup completedCompleteRegistrationStable registration or submission ID
Checkout or plan selection that starts checkoutInitiateCheckoutStable checkout ID
Trial startedStartTrialStable trial-start submission or transaction ID
Payment completedPurchaseStable billing transaction ID

Each new action gets its own ID; a retry keeps the original one. A customer ID can help match a person, but using it as event_id would collapse that customer’s repeated actions of the same type within the deduplication window.

Filter conversion traffic

Apply Global filters to all mappings, then narrow each mapping with its own event and property filters. (+) For example, require environment = production and ads_consent = true, using properties your application actually records. Hold purchases missing their ID, time, total or currency until the source is corrected.

A browser opt-out does not stop independently captured backend events. Carry the visitor’s advertising-permission decision through to the backend event and require it in the destination filter; stopping browser capture alone cannot enforce that rule. (+)

Turn on Filter out internal and test users after defining the project’s exclusions. Inline person-property rules work in destinations; behavioral cohorts can cause destination-filter errors. (+) Our internal-traffic guide covers the project setup. Allow only the controlled test traffic while validating, then restore the production exclusions.

Event ID and timestamp

Event ID: Use a unique transaction-level identifier, such as an order or booking ID, generated only once and kept fixed. Create it at the conversion and pass the same string to the Pixel and PostHog. TikTok deduplicates on the Pixel ID, event name and event_id: it keeps the first event and discards repeats received within 48 hours, attempting to merge data from a duplicate received within five minutes. (+)

The default {event.uuid} identifies a PostHog event. An independently installed Pixel, such as Shopify, Google Tag Manager or a ttq.track call, will not share it unless you deliberately pass one ID to both. For a purchase, replace the default with {toString(event.properties.order_id)} and send the same order ID as the Pixel event’s event_id, in the third argument of ttq.track: (+)

const eventId = String(order.id);
ttq.track(
  'Purchase',
  { value: order.total, currency: order.currency },
  { event_id: eventId }
);

Run it only after the purchase is confirmed and advertising permission is present.

PostHog’s own TikTok Pixel site destination also defaults to {event.uuid}. Those defaults can match when both destinations send the same PostHog event to the same pixel with the same TikTok event name. (+)

Event timestamp: Use the timestamp that reflects when the event actually happened. If you have a custom event time available, map that here. TikTok expects integer Unix seconds; replace {toUnixTimestamp(event.timestamp)} with {toInt(toUnixTimestamp(event.timestamp))}. The default can produce decimal seconds when the source time includes milliseconds. (+ / +) Giving an old order a new processing time misstates when it happened.

Event properties

For purchase-related events, send the total order value rather than the unit price. Always send this as a numeric value only. Do not include currency symbols, commas, text, or other non-numeric characters. Send amounts in the currency’s major units; convert integer cents upstream if that is how your source stores money.

Send the order’s actual supported ISO 4217 currency code with its value. Both fields are required for return on ad spend reporting and value-based optimization. content_ids, contents and content_type are required for Video Shopping Ads (VSA), even though product fields are recommended rather than universally required for other conversions. For web events, page.url is required. (+)

TikTok Ads Conversions property mappings for event and page properties
The template’s single-product Property properties and Page properties defaults. Multi-product mappings use the array expressions in the table below.
FieldPostHog’s multi-product defaultWhat to change and why
value{toFloat(event.properties.value ?? event.properties.revenue ?? event.properties.price)}For purchases, use the confirmed total, for example {toFloat(event.properties.value)}. The default can fall back to a unit price, understating a multi-item order.
currency{event.properties.currency ?? 'USD'}Map {event.properties.currency} to the order’s actual currency. Keep a USD fallback only if every selected order is guaranteed to be in USD; otherwise it mislabels missing-currency orders. The default also sends USD when no value exists.
content_ids{arrayMap(x -> x.sku, event.properties.products ?? [])}Use string IDs that match the catalog’s sku_id or item_group_id. For numeric source IDs, use {arrayMap(x -> toString(x.sku), event.properties.products ?? [])}.
content_typeproductUse product if the IDs in content_ids or contents represent individual products; use product_group if they represent product groups.
contents{arrayMap(x -> ({'price': x.price, 'content_id': x.sku, 'content_category': x.category, 'content_name': x.name, 'brand': x.brand}), event.properties.products ?? [])}Keep content_id a string and price numeric. A minimal mapping that does both: {arrayMap(x -> ({'content_id': toString(x.sku), 'price': toFloat(x.price)}), event.properties.products ?? [])}; add the other fields only if you collect them.
num_items{arrayReduce((acc, curr) -> acc + curr.quantity, event.properties.products ?? [], 0)}Keep it when each product carries its quantity: it sums the quantities, which is what TikTok means, rather than counting product rows.
order_id{event.properties.order_id}Send the order’s unique identifier as a string, using {toString(event.properties.order_id)} if needed. This property does not replace the separate Event ID field.

Single-product mappings instead prefill content_ids with {not empty(event.properties.sku) ? [event.properties.sku] : []} and num_items with {event.properties.quantity}. Their contents array is omitted unless all five source fields—sku, price, category, name and brand—are present. A missing brand can therefore remove the entire product object; replace that condition with a mapping that fits your product data.

Page properties

Use the full URL where the conversion happened. The template drops empty page values, so a backend purchase needs the relevant checkout or conversion URL carried into its source event.

FieldPostHog’s defaultUse
url{event.properties.$current_url}The conversion’s website URL. Map a stored checkout URL when the backend event has no $current_url.
referrer{event.properties.$referrer}The genuine referring URL, when available. Leave it absent if unknown.

Check the API response

Check TikTok’s response code as well as the HTTP status. A successful Events API response has code: 0; use the message field to diagnose a rejected payload. (+)

The template’s final condition checks only res.status >= 400. In the source editor, replace the expression inside that final if (...) with the following, keeping the existing error handler. A non-zero TikTok code then fails the invocation even when the HTTP status is below 400, and an HTTP error still reaches the handler without its body being read for a code. (+ / +)

res.status >= 400 ? true : res.body.code != 0

Validate the setup with a test event code

During testing, include TikTok’s Test Event Code so you can preview and verify the events that PostHog sends. In Events Manager, open the pixel’s Test Events tab and copy the code from Step 2 of Test Server Events; paste it into PostHog’s Test Event Code input. (+)

PostHog’s test panel makes a real HTTP request by default. Keep the TikTok test code in place while testing; the panel’s Make real HTTP requests switch controls whether the request is sent or mocked. (+ / +)

  1. Use a controlled conversion. Inspect the mapped event name, string event ID, original time, page URL, matching fields, total and currency.
  2. Check both the HTTP status and TikTok’s response code, then find the event in TikTok’s Test Events activity.
  3. Send the browser and server versions with the same Pixel ID, event name and event ID. Repeat that ID to check deduplication; send a new conversion with a new ID to check it is retained.
  4. Check the filters with denied advertising permission, internal traffic and missing required fields. Those captures should not reach TikTok.

After you validate the integration, remove the test code from the configuration. From that point forward, TikTok will treat all incoming events as live data.

Save and enable the destination with the production filters restored. Then check an authorized real conversion in three places:

OutcomeWhere to checkWhat it establishes
DeliveredPostHog’s invocation response, then the pixel’s Overview in Events Manager. Look for Server under Connection Method.TikTok received the server event. If both channels send it, compare Browser, Server and Server & Browser; the combined metric should count the pair once. (+)
MatchedEvents Manager’s event details, Event Match Quality and diagnostics.Inspect match-key coverage and matching issues. Event Match Quality is a weighted average of match-key coverage, not proof that a particular conversion matched a person. (+)
AttributedCampaign conversion reporting in TikTok Ads Manager, using the ad group’s attribution settings.TikTok credited an ad interaction within its attribution window. Receipt alone does not establish campaign credit. (+)

Compare unique conversion IDs and values with your source orders, using the same time range, timezone and filters. TikTok’s event totals include attributed and unattributed events, and its Overview can lag behind receipt. Our conversion tracking audit explains how to reconcile those differences.

Troubleshooting TikTok conversions

SymptomWhat to check
No test eventCheck the Pixel ID, token’s ad account, selected mapping and Test Event Code. In PostHog’s test panel, check that real HTTP requests are enabled.
PostHog shows success but TikTok shows nothingInspect the full response body, not just the HTTP status. Apply the response-code check above and inspect TikTok’s diagnostics.
Email or phone matching is poorCheck trimming and lowercasing for email; validate E.164 with its leading + for phone; hash each once. Check that person data existed before the conversion was processed.
Missing click or device contextCheck the latest ttclid, masking, ttp capture and whether the IP/user agent describe the visitor or the server.
Duplicate purchasesInventory browser tags and other server integrations. Compare Pixel ID, event name and event ID on both copies; retries must retain the conversion ID.
Value or product data is wrongCheck order total versus unit price, minor versus major currency units, the USD fallback, catalog ID types, quantities and the single-product contents condition.
Receipt without ad creditCheck matching diagnostics, the original conversion time, the ad group’s attribution window and reporting delay.

Frequently asked questions

Can I send several TikTok event types through one destination?

Yes. Give each action its own mapping and fields. If one source event matches two mappings, PostHog runs both (+), so check overlapping filters when an event appears twice. Split destinations when you need different pixel credentials or separate control over consent and ownership.

Can I use this template for app or offline events?

No. This template fixes event_source to web. Changing the event name does not change that source type. App or offline conversions need an implementation with the correct source ID, source type and required parameters. (+)

What if ttclid is missing?

You can send a conversion with other available matching fields, such as hashed email, phone, or the visitor’s IP and user agent. (+) If the visitor arrived from a TikTok ad, check whether redirects lost the click ID or whether it stayed on an anonymous event instead of the person profile. Do not invent a click ID for traffic from another source.

Should missing currency default to USD?

Only when every purchase selected by that mapping is guaranteed to use USD. Otherwise hold the incomplete purchase and fix the source.

Does a test event prove ad attribution?

No. It lets you inspect receipt and payload configuration. Events Manager counts both attributed and unattributed events, so seeing an event there does not prove an ad received credit. After removing the code, verify a real conversion’s matching, deduplication and campaign reporting separately. (+ / +)

What should I monitor after launch?

Watch destination failures, disabled destinations, missing matching fields, duplicate conversion IDs and order values. PostHog exposes destination metrics and errors, and can disable a destination after prolonged failures. (+) Repeat the paired browser/server check after changing the token, source schema, checkout or any other integration that sends the same conversions.

About the author

Moein Heshmati

Moein Heshmati

Moein Heshmati leads data systems and engineering at 99Ways, specializing in analytics engineering, tracking, and experimentation systems. He writes about data quality, measurement, technical implementation, and reliable experimentation.

More articles

Where is growth getting stuck?

Book a free 45-minute call with Iman. Show him your site and, if you can, your analytics. You’ll leave knowing what to fix or test first.

Book a free call