DataStated Documentation Add my site
Add my site

Connect TikTok Ads

When a TikTok connection is available, compare its reported purchase count with processor-confirmed orders attributed to TikTok Ads. Campaign, ad-group and ad reports contain TikTok's own results; monetary comparisons require known USD ad currency and compatible processor-confirmed payments.

Requires TikTok access to be enabled for this deployment

As of September 11, 2026, hosted TikTok connection is unavailable. Provider-console access, deployment setup and a successful live pull are still pending. The steps below describe the implemented flow, not a verified live connection. Contact hello@datastated.com for availability.

1. Tag your ads

The comparison only works if your site can tell which visits came from TikTok. The tag reads two things from the landing URL: the ttclid click id TikTok appends to ad clicks, and utm_source. A click id wins when it is present; utm_source is the fallback, and the referrer comes after that. A visit counts as TikTok Ads when it carries a ttclid, or a utm_source of tiktok beside a paid utm_medium (paid, cpc and the rest of the paid mediums). A visit from tiktok.com with neither is organic TikTok, its own channel, and stays out of the TikTok Ads row.

Click ids alone are not enough. Safari on iOS strips known click identifiers from links opened out of Mail, Messages and private browsing, and TikTok clicks open in its in-app browser, which often arrives with no referrer at all, so an untagged click lands as direct. UTM parameters survive. In TikTok Ads Manager, add them to each ad's destination URL (or the ad group's URL parameters):

utm_source=tiktok&utm_medium=paid&utm_campaign=__CAMPAIGN_NAME__&utm_content=__CID_NAME__

2. Connect

  • Open your site's settings in the dashboard, choose the Revenue tab, and in the TikTok Ads card click Connect TikTok Ads. Only a site owner can do this.
  • TikTok's authorization page (business-api.tiktok.com/portal/auth) asks you to approve the DataStated app for your TikTok for Business login. The card says it plainly: "Read-only: no changes are made to your account."
  • Back in DataStated, a login with one advertiser connects on the spot. Several show a picker under "Connected. Which TikTok advertiser should spend come from?", listing each advertiser's name and id; pick one and click Connect advertiser. A login with none is told "That TikTok login has no ad accounts on it. Connect a login that manages your TikTok ads."

The card then shows the advertiser id, the day it connected and a connected badge, with Reconnect and Disconnect beside it. The access token is sealed with AES-256-GCM before it is stored and never shown to anyone. When TikTok issues a refresh token, the worker refreshes access before it expires; when it issues a long-lived token there is nothing to refresh. Either way, "Access renews on its own; if it ever lapses, this card asks you to reconnect." Disconnect "stops pulling spend from this advertiser and forgets DataStated's access token. Numbers already pulled stay here." TikTok has no server-side revocation for these grants, so to remove the app on TikTok's side as well, open TikTok Ads Manager, Tools, Authorized apps.

Each sync asks TikTok's integrated report for daily spend, impressions, clicks, completed payments and their value per campaign, and the same rows per ad group and ad. Web purchases are read first and app purchases only as the fallback, so a sale TikTok reports under both is counted once. Nothing is written to your account.

Want the layout before you connect? Under Connections, Add a connection with TikTok Ads as the platform and Add example data puts made-up TikTok numbers on your dashboard; remove them any time with Remove. If you run your own DataStated server, the card reads "This deployment is not set up for TikTok yet" until the operator adds the app's credentials.

3. What you will see

Numbers come in on the sync that runs every six hours, and the first pass reaches 90 days back, with completion depending on the account size and successful provider reads. The TikTok row of the comparison exists only once TikTok numbers have landed, real or example, so until then you will not see it at all. To pull sooner, call the API:

curl -X POST -H "Authorization: Bearer dsk_YOUR_KEY" \
  https://app.datastated.com/api/sites/acme.com/sync

The What each platform claims panel shows platform-claimed conversion counts beside processor-confirmed orders attributed to its paid channel. Orders without payment confirmation are listed separately. Example claims are labeled; they are not results from your account.

For a window whose ad records all carry provider-reported USD, the Money section shows spend and platform-reported revenue, CPC and ROAS. Campaign, ad-set/ad-group and ad rows remain platform reports. Revenue gaps and efficiency figures also require processor-confirmed payments with compatible USD currency. Unknown, mixed or non-USD ad currency leaves combined dollar figures unavailable and shows currency groups separately, without conversion. Re-sync older records to obtain their account currency. Journey rows separately show Touched, Started and Closed. See comparison scope.

4. Why the numbers differ

TikTok counts a completed payment when someone buys within its attribution window after clicking an ad, or after only watching one. Your site records the visit that happened and the order that followed. Someone who watched on their phone and bought on a laptop is a TikTok sale and a direct order on your site, and an in-app browser visit that arrives untagged lands as direct too, which is why step 1 matters more here than on any other platform. Your site misses anyone running an ad blocker, and TikTok grades its own homework. The two reports use different evidence and do not establish a lower or upper bound on the sales an ad caused.

5. Troubleshooting

  • No spend showing. Check the currency-scope notice. Combined dollar amounts need known USD ad currency; older rows with unknown currency need a re-sync. Mixed or non-USD amounts are not converted. For missing activity, also check the selected account and date range.
  • Claims but no attributed orders. TikTok reported payments and your site recorded no order from a TikTok-tagged visit. Confirm the tag is installed and orders are tracked (Goals and orders), then open the UTM sources tab and check what arrived: a utm_source spelled any way but tiktok, or a utm_medium that is not a paid one, is the usual cause.
  • The card says access has lapsed. "TikTok access has lapsed, so spend has stopped updating. Reconnect to resume. It takes a few seconds." Click Reconnect TikTok; the advertiser you chose stays bound. "Connected, but we could not read your advertisers from TikTok" at the picker step means the same thing, and so does "TikTok could not confirm access. Please connect again."
  • "That does not look like a TikTok advertiser id." The picker posts the id it listed; if you typed one, it is the long number under the account name in TikTok Ads Manager, digits only.
  • Example numbers still showing. Example data and a real connection can sit side by side; remove the example row once the real one has synced, or the panel keeps badging TikTok's side Example.

Questions? Email us at hello@datastated.com.