TikTok Ads

TikTok Ads

This connector reads and manages a TikTok advertising account through the TikTok API for Business (Marketing API v1.3, https://business-api.tiktok.com/open_api/v1.3): the ad account, campaigns (also Smart+), ad groups, ads, performance reports, custom and saved audiences, pixels, the video and image library and identities. It can pause or turn on campaigns, ad groups and ads and change campaign budgets; those tools are installed switched off. It creates nothing.

Setup (about 15 minutes, plus TikTok's app review)

1. Sign in at the TikTok API for Business developer portal (https://business-api.tiktok.com/portal) with a TikTok for Business account that has access to the ad account, and click Become a Developer (fill in the company details).
2. My Apps → Create an app: name, description, an Advertiser redirect URL (any https page of yours; the connector does not use it, you only copy a code from its address) and the permission scopes: at least Ad Account Management, Ads Management, Reporting and Audience Management, plus Pixel Management and Creative Management for those tools. TikTok reviews new apps, usually within two or three business days.
3. When the app is approved, open it under My Apps: copy the App ID and Secret into TIKTOK_ADS_APP_ID and TIKTOK_ADS_APP_SECRET (used only to list the authorized ad accounts). Open the Advertiser authorization URL shown there, sign in, tick the ad accounts and confirm. The browser lands on your redirect URL with auth_code=... in the address bar; the code works once and expires after an hour.
4. Exchange the code for the access token right away: curl -X POST https://business-api.tiktok.com/open_api/v1.3/oauth2/access_token/ -H "Content-Type: application/json" -d '{"app_id":"<App ID>","secret":"<Secret>","auth_code":"<auth_code>"}' The answer holds data.access_token and data.advertiser_ids. Paste the token into TIKTOK_ADS_ACCESS_TOKEN and one of the ids into TIKTOK_ADS_ADVERTISER_ID. This long-term token does not expire; it stops working when the authorization is revoked or the secret is reset.
5. Set TIKTOK_ADS_API_HOST to https://business-api.tiktok.com, install and run tiktok_ads_get_advertiser_info.

Sandbox: for tests without real spend, open the app in the developer portal → Sandbox, create a sandbox ad account and generate its access token there (no review needed). Use that token and sandbox advertiser id, and set TIKTOK_ADS_API_HOST to https://sandbox-ads.tiktok.com. Sandbox accounts deliver nothing and report no real data.

One ad account per connector: every tool works on TIKTOK_ADS_ADVERTISER_ID. A token often covers several accounts (tiktok_ads_list_authorized_advertisers lists them); install the connector again for another account.

Changes spend money: confirm first. tiktok_ads_update_campaign_status, tiktok_ads_update_ad_group_status and tiktok_ads_update_ad_status (ENABLE starts spending, DISABLE pauses) and tiktok_ads_update_campaign_budget act at once. They are installed switched off; once switched on, state the object (name and id), the current and the new value, and wait for the user's yes. An ad delivers only when the ad, its ad group and its campaign are all on. Budgets are decimal amounts in the account currency (50 = 50.00), not cents; TikTok refuses a budget below its minimum or below 105% of what has already been spent. Ad group budgets are not offered: TikTok's ad group update replaces the whole ad group.

JSON in parameters: TikTok takes lists and filters as JSON text in the query, so fields, filtering, dimensions, metrics, pixel_ids, video_ids, image_ids and custom_audience_ids are strings holding JSON, e.g. ["spend","clicks"] or {"campaign_ids":["1800..."]}.

Reports (tiktok_ads_get_report)

• Pick the level with data_level and the matching ID dimension: AUCTION_CAMPAIGN with campaign_id, AUCTION_ADGROUP with adgroup_id, AUCTION_AD with ad_id, AUCTION_ADVERTISER with advertiser_id. Use one ID dimension and at most one time dimension: stat_time_day for daily rows (at most 30 days per request; split longer periods) or stat_time_hour (one day). Without a time dimension a request may span up to 365 days.
• Names come as metrics: add campaign_name, adgroup_name or ad_name to metrics.
• Audience breakdowns need report_type AUDIENCE with dimensions such as age, gender, country_code or placement; not every metric is available there.
• Dates are in the ad account's timezone; spend and costs are in the account currency. Metrics come back as strings.
• Not every combination of dimensions and metrics is allowed; the error message names the one that is not.

Lists return their items in data.list[] (data.pixels[], data.saved_audiences[] and data.identity_list[] for pixels, saved audiences and identities) and data.page_info (page, page_size, total_number, total_page); ask for the next page while page < total_page. Ids are long numbers: pass them as strings.

Errors arrive with HTTP 200: TikTok puts the result in code (0 = success) and message; the connector turns other codes into errors.

• 40001: the app or token has no permission for this ad account or action (scope missing in the app, account not authorized). Authorize the ad account again with the needed scopes.
• 40100, 40016, 40133: too many requests; wait a moment and try again.
• 40104, 40105, 40102, 40106: the access token is missing, invalid, expired or revoked, or does not belong to this ad account; generate a new one.
• 40118 to 40125: the app or ad account is not allowed this feature or permission.
• 40300, 40301: TikTok does not know the advertiser id.
• 40002 and other 4xxxx codes: a parameter is wrong or missing; message names it.
• 5xxxx, 60001: a TikTok server error or maintenance; try again later.

Out of scope here: creating or editing campaigns, ad groups, ads and audiences, uploading creatives, asynchronous report tasks, Business Center management, the Events API and TikTok Shop (GMV Max).