TikTok For Business

Reads campaigns and ad groups, daily spend by country and per-ad results (2-second views, plays to the end, taps).

Implemented against the documented Business API v1.3, not yet tested against a live account. Please report what you see.

"tiktok": { "enabled": true, "redirectUri": "https://your-site.example/earnback", "advertisers": [] }

Your TikTok developer app

TikTok gives API access per developer app, and every Earnback user registers their own.

1. Sign in at business-api.tiktok.com/portal with the TikTok For Business account that owns your ads, and Become a developer.
2. Create an app. For “what best describes you” pick Direct Advertiser. Describe the use honestly: reading your own campaign performance into a local dashboard.
3. Permissions: tick the Ad Account Management and Reporting scopes Earnback reads (advertiser info, campaigns, ad groups, ads, reports). Earnback never writes, so you don’t need creation scopes for it.
4. Advertiser redirect URL: TikTok requires https, so use a page of your own website (any page works, it is only where the browser lands with the code). Put the same URL in redirectUri.
5. Wait for approval (usually a few days). Then copy the App ID and Secret and save them as tiktok-app.json in your secrets folder:

{ "app_id": "7…", "secret": "…" }

Connect

earnback connect tiktok

1. Your browser opens TikTok’s consent page. Pick your advertiser account and confirm.
2. TikTok sends the browser to your redirect page with ?auth_code=…&state=… in the address.
3. Copy the full address from the address bar and paste it into the terminal.

Earnback checks the state, exchanges the code for a long-term token and saves it as tiktok-token.json. The token stays valid until you revoke it in TikTok.

What it reads

• Campaigns and ad groups: name, status, objective, budget mode and amount, schedule, optimisation goal, locations.
• Daily spend, impressions and clicks per campaign and country (audience report).
• Per ad and day: spend, impressions, clicks, 2-second views and plays to the end.

Reports are requested in 30-day chunks (the API’s limit). The last 28 days are re-read on every sync.

Caveats

• Without an attribution partner or TikTok’s SDK in your app, TikTok sees store taps, not installs. Players come from GA4 (first-user source containing tiktok); expect undercounting.
• TikTok’s hook rate uses 2-second views (TikTok’s own short view), Meta’s uses 3-second plays. Compare videos within one channel.
• Creating campaigns is out of scope (Earnback is read-only). If you build tooling that creates TikTok app campaigns: from 2027-01-01 TikTok only accepts the Smart+ campaign APIs for that.

Errors