TikTok (Events API)
TikTok (Events API) is a traffic source (social). Its own documentation: https://business-api.tiktok.com/portal/docs/events-api-2.0/v1.3.
What it connects
Section titled “What it connects”- Sends your conversions back to TikTok (Events API), with a test conversion to check it.
- Pulls your spend from its API.
- Lists placements to block, for you to export; nothing is sent.
- Pauses and resumes its campaigns, ad groups and ads.
- Sets bids on its ad groups.
- Sets daily budgets on its campaigns and ad groups.
- Checks the connection with a harmless request when you test it.
How to connect it
Section titled “How to connect it”API key. Sent in the Access-Token header.
Set these on the connection:
| Field | Name | Kind | What to enter |
|---|---|---|---|
| Pixel code | pixel_code | string, required | In TikTok Events Manager, your web pixel’s id |
| Events API access token | access_token | string, required, secret | In TikTok Events Manager, your pixel’s Settings, under Events API, Generate Access Token |
| Test event code | test_event_code | string | From Events Manager’s Test events tab. Only a test conversion carries it, never a live event, so it’s safe to leave set |
| Advertiser id | advertiser_id | string | For spend and pausing, the ad account’s id, in TikTok Ads Manager under your account’s name |
| Advertiser time zone | advertiser_time_zone | string | For spend, the ad account’s time zone, such as Europe/Berlin, in its Account info; TikTok reports spend by its days |
| Advertiser currency | advertiser_currency | string | For spend, bids and budgets, the ad account’s currency, such as EUR, in its Account info |
| Reporting access token | reporting_token | string, secret | For spend, a TikTok API for Business access token with the Reporting permission on the ad account, from a developer app it authorized |
| Ads management token | ads_management_token | string, secret | For pausing and resuming campaigns, ad groups and ads, and setting their bids and budgets, a TikTok API for Business access token with the Ads Management permission on the ad account, from a developer app it authorized |
A secret is set by the workspace’s owner alone and never shown again. A required secret that is missing holds the connection’s deliveries until it is set; one that is optional holds only what reads it.
Tracking macros
Section titled “Tracking macros”Each token is a query parameter on the campaign URL; the source replaces its macro with the value when it sends the visitor. The columns say which part of the visit it fills and which report column (v1 to v20) it lands in.
| Parameter | Macro | Fills | Report column |
|---|---|---|---|
ttclid | added by the platform itself | The source’s click id | |
cmp | __CAMPAIGN_ID__ | Source campaign | v1 (Campaign) |
adg | __AID__ | Custom value | v2 (Ad group) |
ad | __CID__ | Creative | v3 (Ad) |
plc | __PLACEMENT__ | Placement | v4 (Placement) |
The campaign URL you paste into the source is the tracking domain, the campaign’s key and the tokens the source fills, in this order (the domain below is an example, and {url_key} stands for the campaign’s own key):
https://trk.example.com/{url_key}?cmp=__CAMPAIGN_ID__&adg=__AID__&ad=__CID__&plc=__PLACEMENT__Cost models, the first the default: none (no cost), cpm (cost per thousand visits), cpa (cost per conversion), api (the spend pulled from the source’s API).
Preview the campaign URL
Section titled “Preview the campaign URL”Campaign URL
Paste the campaign URL into the source's ad. {url_key} stands for the campaign's own key, which the portal fills in; the macros are the source's, which it replaces with each visit's values.
How conversions get back to it
Section titled “How conversions get back to it”Tallyray sends a conversion to TikTok (Events API) when it enters one of these statuses: approved. A conversion is sent once per status it enters; an adjustment, with revenue moving and its status not, isn’t sent. A conversion older than 167h isn’t sent.
Tallyray’s event kinds, and the name each is sent as. A conversion of a kind not listed isn’t sent:
| Tallyray event | Sent to TikTok (Events API) as |
|---|---|
lead | SubmitForm |
registration | CompleteRegistration |
sale | Purchase |
deposit | Purchase |
subscription | Subscribe |
The request: POST https://business-api.tiktok.com/open_api/v1.3/event/track/ (in batches, up to 1000 conversions each).
A conversion is sent only when this holds:
=visit.external_click_id != '' || conv.user.em != '' || conv.user.ph_e164 != ''This template sends personal data, so it honors consent: for a visit from the EEA, the UK or Switzerland without ad_user_data granted, the conversion goes without anything personal, including the platform’s click id, and is not sent when nothing is left to match on. An explicit denial withholds the person’s hashed identifiers wherever the visit came from.
It reads these personal fields of the visit: ip, user_agent, page_url.
Test conversion. You can send one from the portal to check the connection. TikTok shows it in Events Manager’s Test events tab, under your test event code A test needs this first: Set the test event code from Events Manager’s Test events tab first, so TikTok keeps the test apart from your live events.
Conversions are retried when the source can’t be reached or answers with an error that can pass; see the limits below.
Tallyray pulls spend from the source’s API every 3h, covering the last 3d again, as sources restate spend, 7d at most per request, by day, in the zone =conn.advertiser_time_zone. With api among the cost models, a campaign is priced by it.
The request: GET https://business-api.tiktok.com/open_api/v1.3/report/integrated/get/.
Pulling spend needs the API’s credential. A connection without it goes on sending conversions and pulls no spend.
Placements
Section titled “Placements”Placements are the visit’s placement value, as the tokens above fill it.
This template has no block request: Tallyray keeps the blocks as a list you export into the source, and sends nothing.
Pausing and resuming
Section titled “Pausing and resuming”Rules and reports can pause and resume the source’s own objects at these levels. Tallyray reads an object before it writes, and writes only what isn’t so already, so a repeated pause never toggles anything.
| Level | Named by |
|---|---|
| campaigns | cmp |
| ad groups | adg |
| ads | ad |
Rules and reports can set the source’s bids at these levels. Each value is read before it’s written, in the account’s currency, never converted; a value the source sets itself isn’t written.
| Level | Named by | Prices | Bounds | Notes |
|---|---|---|---|---|
| ad groups | adg | cpc, cpm, cpa | step minor |
Daily budgets
Section titled “Daily budgets”Rules and reports can set the source’s daily budgets at these levels, read before they’re written, in the account’s currency.
| Level | Named by | Prices | Bounds | Notes |
|---|---|---|---|---|
| campaigns | cmp | daily | step minor | |
| ad groups | adg | daily | step minor |
Limits
Section titled “Limits”- Rate: at most
20/sper connection, 4 at once. - Retries: up to 12 attempts, waiting from
30sand doubling up to2h, longer when the source’sRetry-Afterasks, and never past the conversion’s age limit. - Hosts it reaches:
business-api.tiktok.com. No other. - What a connection may override:
/conversions/events,/conversions/send_on,/tokens,/cost. Hosts, authentication and requests never are, and an override may only lower the limits.
This page describes version 5 of the TikTok (Events API) template, the latest published. The version your connection runs is the one your administrators approved, and the portal shows it.