TikTok Events API 2.0: Pixel plus Server-Events mit ttclid, _ttp und gemeinsamer event_id

Was du aus dem TikTok Ads Manager brauchst

• Den Pixel-Code (Events Manager → Web-Events → dein Pixel). Er ist öffentlich und dient zugleich als event_source_id für die API.
• Einen Events-API-Access-Token (Pixel → Einstellungen → Access-Token erzeugen). Er ist ein Geheimnis und gehört in den Tresor, nie in ein Tag.
• Optional einen Test-Event-Code aus dem Tab Test-Events.

Der Request

POST https://business-api.tiktok.com/open_api/v1.3/event/track/ mit dem Header Access-Token: <token> und einem Body wie:

{
  "event_source": "web",
  "event_source_id": "CABCDEFGHIJKLMNOPQRS",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1767225600,
    "event_id": "01J9EXAMPLESOURCEEVENTID00",
    "user": { "ttclid": "…", "ttp": "…", "email": "<sha256>", "phone": "<sha256>", "external_id": "<sha256>" },
    "page": { "url": "https://shop.example/danke", "referrer": "https://shop.example/checkout" },
    "properties": { "value": 129.9, "currency": "EUR", "content_type": "product", "contents": [{ "content_id": "SKU-1", "quantity": 1, "price": 99.9 }], "order_id": "A1001" }
  }]
}

Ein code: 0 in der Antwort bedeutet angenommen. event_time sind Unix-Sekunden; event_source kann für Nicht-Web-Quellen auch offline oder crm sein, jeweils mit der ID des passenden Event-Sets.

Eventnamen

TikToks Standard-Web-Events sind in PascalCase: ViewContent, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, CompletePayment, PlaceAnOrder, CompleteRegistration, SubmitForm, Contact, Subscribe, StartTrial, Download, Search, Schedule, ClickButton. Track bildet die kanonischen Events standardmäßig darauf ab (purchase → CompletePayment, generate_lead → SubmitForm, book_appointment → Schedule) und lässt dich pro Destination überschreiben.

Matching-Schlüssel, nach Wirkung sortiert

1. ttclid — die Click-ID, die TikTok an Landingpages anhängt. Nach Marketing-Consent erfassen, First-Party speichern und mit jedem Server-Event im Attributionsfenster senden.
2. ttp — der Wert des Cookies _ttp, das das Pixel setzt. Er identifiziert den Browser gegenüber TikTok ohne personenbezogene Daten.
3. email und phone — nach Normalisierung SHA-256-gehasht (E-Mail in Kleinschreibung, Telefon in E.164).
4. external_id — deine eigene Nutzer-ID, gehasht.

ttclid und ttp aus dem Browser-Weg plus gehashte E-Mail aus dem Bestellsystem ist die Kombination mit der höchsten Match-Rate.

Deduplizierung zwischen Pixel und API

TikTok dedupliziert über event_id, wenn derselbe Eventname vom Pixel (ttq.track('CompletePayment', {...}, { event_id })) und von der API innerhalb des Dedup-Fensters eintrifft. Erzeuge eine ID pro Aktion und gib sie beiden mit; das Track-SDK macht das automatisch für jedes gespiegelte Event.

Sicher testen

Trage den Test-Event-Code aus dem Events Manager in die Einstellungen der Destination ein. Solange die Destination im Testmodus ist, trägt jeder Request test_event_code; Events erscheinen unter Test-Events und bleiben aus dem Reporting ausgeschlossen. Der Assistent sendet einen markierten Kauf und zeigt TikToks Antwort inklusive der request_id, die du beim TikTok-Support nennen kannst.

Antwortcodes, die man kennen sollte

• 40001 — Access-Token ungültig oder fehlt → Token rotieren
• 40002 / 40000 — Parameterfehler → Eventnamen, Zeitstempel und Hashing prüfen
• 40100 — Rate-Limit → wird mit Backoff wiederholt
• HTTP 5xx — temporär → wird wiederholt, Circuit Breaker bei Andauern

Limits

Bis zu 1.000 Events pro Request, Zeitstempel innerhalb der letzten sieben Tage, und der Pixel-Code muss zum Werbekonto gehören, das den Token ausgestellt hat. Offline-Events nutzen die ID des Offline-Event-Sets als event_source_id und event_source: "offline".