Direct integration setup with TikTok

This guide walks through our native TikTok integration from start to finish.

Once it's set up, we send your conversions and custom events straight to TikTok's Events API, pull campaign spend into your reports, and show your campaign, ad group and ad names instead of raw IDs.

If you're unsure about any of the settings below, use our TikTok traffic source template when you create the traffic source. Everything will be configured correctly.

If you haven't yet, read Using traffic source integrations first -- it explains the general flow (connections, traffic source link, event mapping) that applies to every platform. This article only adds the TikTok-specific parts.

Note that the older method, where you build a TikTok custom scenario with your own access token, still works and is described in Using the TikTok API for tracking conversions. For new setups we recommend the native integration -- there is no token to copy around, and you get cost and name sync on top.

Step 1: Connect your TikTok account

Go to Settings > Integrations > Traffic Sources and find the TikTok card.

Click Connect (or Add account if you already have a TikTok connection) and you'll be sent to TikTok for Business to log in and approve access.

Log in with the TikTok login that has access to the ad accounts you advertise from.

When you come back, the connection appears under Connections with an Active status.

If it ever shows Expired or Auth error, click Reauth to log in again.

Step 2: Link the traffic source to your TikTok ad account

Open your TikTok traffic source (or create one from the TikTok template) and go to the Integrations tab.

In Platform Integration, fill in the fields from top to bottom -- each one appears once the previous one is set:

1. Traffic Source Integration Type -- TikTok. If the traffic source used our TikTok custom scenario before, or has "TikTok" in its name, we pre-select this for you.
2. Connection -- the TikTok login you connected in Settings.
3. Ad Account -- the TikTok ad account this traffic source spends from.
4. Event Source / Pixel Code -- the TikTok pixel that events should be sent to.
5. TikTok Test Event Code -- optional, see below.

The chips at the top right (Platform > Connection > Ad account > Event Source / Pixel Code) turn green as each step is done.

Picking the pixel

Once the ad account is selected, we load the pixels from that account, so you can just pick one from the Event Source / Pixel Code dropdown.

If your pixel isn't listed, or the list fails to load, click Enter ID manually and paste it in. Select from account pixels switches back to the list.

When entering it manually, use the pixel code shown in TikTok Events Manager (the same code that's in your pixel's JS snippet). Do NOT use the numeric pixel ID from TikTok's Marketing API -- TikTok rejects events sent to that one with a permission error.

Test event code

TikTok Test Event Code is optional.

If you copy a test code from the Test Events tab in TikTok Events Manager into this field, the events we send are routed to TikTok's Test Events view, so you can watch them arrive while checking your setup.

Clear it once you're done testing, so your events go to the pixel normally.

Step 3: Check your tracking fields

TikTok matches conversions back to ad clicks mainly using the TikTok click ID, ttclid.

For us to send it, the click ID needs to be captured in the External Click ID tracking field. On the Tracking Fields tab, check that the External Click ID row has ttclid as the URL parameter and __CLICKID__ as the source token.

If you created the traffic source from our TikTok template, this is already done for you.

A few other things also help TikTok match events, and we send them automatically where available:

• The _ttp browser cookie, picked up by our JS tag when it's present on your page.
• The URL of the lander or offer page the visitor was on, plus the referrer.
• Email, phone and external ID when we have them for that visitor, hashed before sending.

Step 4: Map your events

Go to the Conversion Tracking tab and switch the toggle at the top from Classic Options to Integrations.

For each event you want to send:

1. Pick a Triggering Event -- Conversions or one of your custom events.
2. Pick a Destination Event -- one of TikTok's standard events such as Complete Payment, Add to Cart or Submit Form, or type your own custom event name.
3. Optionally set a Value Override, Currency Override or webhooks.

Each TikTok event can only be used once per traffic source, so one conversion is never counted twice in TikTok.

Remember that saving in Integrations mode removes the traffic source's classic postback and custom scenario settings. That's on purpose -- otherwise TikTok would receive every conversion twice. If you're moving over from the old TikTok custom scenario, note down your settings first in case you want to go back.

Then click Save.

TikTok has no delay on conversions, so they are sent as soon as they happen.

Step 5: Turn on cost sync and name sync

Back on the Integrations tab, below Platform Integration, you'll find Cost Sync and Dictionary Sync.

Cost Sync

• Enable campaign-level cost sync -- imports campaign spend from TikTok every hour.
• Reconcile finalized daily costs -- rechecks each finished day once TikTok has finalized its numbers, so your costs end up matching TikTok's own reporting.

After saving, the Sync status panel shows the last and next runs, and you can use Sync hourly costs now or Reconcile daily costs now if you don't want to wait.

Note that this is campaign-level ONLY. If you need spend per ad group or per ad, that's available through Argosync -- click Learn more in that section.

Dictionary Sync

Turn on Enable ID to name sync and we'll pull your campaign, ad group and ad names from TikTok, so reports show "US - Broad - Video 3" instead of a long number.

The table shows which tracking fields we need. For TikTok these are:

If a row says Add field, add a tracking field with that URL value. We match on the URL value, not the field name, so it doesn't matter what you call it. The TikTok template already includes all three.

Show original IDs after synced names keeps the raw ID next to the name, handy when you need to search for it in TikTok Ads Manager.

Checking that events arrive

Go to Logs > Integration Logs.

The Event Logs view lists every event we sent to TikTok: when it was sent, which traffic source it came from, the event type, the destination event, the outcome (e.g. Delivered), and what data was included, such as URL and click ID.

Use the Platforms filter to show only TikTok, and widen the date range if you're looking for older events.

Switch to the Queue view with the toggle next to Apply. It lists events that haven't been sent yet -- Pending, Processing or Held -- with their status, hold reason, platform, integration, traffic source, hit ID and event type.

Held conversions

If your TikTok connection expires, is disconnected, or the link is misconfigured, we don't throw conversions away. They are held in the queue and sent once you fix the problem.

In the Queue view, held rows show the Hold Reason: Credentials invalid, Integration inactive or Configuration error.

Turn on the Resolution and Next Attempt columns under Columns to see what to do about it -- e.g. "Reconnect TikTok integration", which links to the settings page -- and when we retry. For held rows, Next Attempt reads "After fix": nothing is retried until the problem is solved.

Other platforms limit how late a conversion can be uploaded, so their held conversions eventually expire. TikTok doesn't publish such a limit, so held TikTok conversions stay in the queue until you reconnect.

Note that completed items drop out of the Queue view by default. Completed only means the item left the queue -- Event Logs tells you whether TikTok actually accepted it.

Troubleshooting

The pixel list is empty or won't load

Click Enter ID manually and paste the pixel code from TikTok Events Manager. Also check that the TikTok login you connected has access to that pixel.

Events fail with a permission error

Usually this means the pixel ID is the numeric Marketing API ID rather than the pixel code, or your login doesn't have access to that pixel. Re-select it from the list, or check the code in Events Manager.

Events arrive in TikTok but don't attribute to ads

Check the External Click ID tracking field carries ttclid with __CLICKID__, and that your TikTok ads use the tracking link from this traffic source.

My events only show under Test Events

Clear the TikTok Test Event Code field and save.

For anything else, see the troubleshooting section in Using traffic source integrations.

Updated on: 15/10/2026