With user journeys spanning in-store purchases, call center sales, delayed B2B contract signings, and mobile POS checkouts, browser pixels miss a massive percentage of total revenue generated by paid social campaigns. By connecting your CRM or database to the TikTok Offline Events API using Python, you can attribute closed offline conversions back to TikTok ad creatives, optimize automated bidding models toward high-LTV customers, and eliminate conversion leakage.
In this production-ready setup guide, we walk through configuring an Offline Event Set in TikTok Events Manager, writing an asynchronous Python synchronization worker, enforcing SHA-256 PII hashing standards, and preventing duplicate attribution through robust event ID keys.
1. How TikTok Offline Events API Works
Unlike standard web pixel events that track user actions in real time on a website, the Offline Events API processes batch or streaming transactions executed in physical retail, phone orders, or backend CRM systems. TikTok matches these transactions against historical ad impressions, video views, and clicks using normalized customer identifiers (email, phone number, physical address, and device IDs).
| Data Parameter | TikTok Requirement | Normalization & Formatting Rule |
|---|---|---|
event_set_id |
Mandatory root parameter | Unique ID created in TikTok Events Manager > Offline Events. |
action_source |
Mandatory event parameter | Must be explicitly set to "offline" (or "physical_store"). |
email |
Primary matching key | Trim whitespace, lowercase, and encode with SHA-256. |
phone |
Secondary matching key | E.164 international format (+12135550199), stripped of dashes, SHA-256. |
event_id |
Deduplication identifier | Order number or receipt ID string to prevent duplicate revenue logs. |
2. Production Python Synchronization Daemon
Below is a production Python worker that normalizes customer data, generates SHA-256 hashes, builds structured product arrays, and dispatches batch transactions to TikTok’s Open API v1.3 endpoint:
# tiktok_offline_sync.py
import os
import time
import json
import hashlib
import requests
TIKTOK_API_URL = "https://business-api.tiktok.com/open_api/v1.3/event/track/"
TIKTOK_ACCESS_TOKEN = os.environ["TIKTOK_ACCESS_TOKEN"]
TIKTOK_EVENT_SET_ID = os.environ["TIKTOK_EVENT_SET_ID"]
def sha256_hash(val: str) -> str:
# Normalize string by trimming and lowercasing before SHA-256 hashing
if not val:
return ""
clean = val.strip().lower()
return hashlib.sha256(clean.encode("utf-8")).hexdigest()
def normalize_e164_phone(phone: str) -> str:
# Remove non-numeric characters except leading +
digits = "".join([c for c in phone if c.isdigit() or c == "+"])
return sha256_hash(digits)
def push_offline_purchase(order_id: str, email: str, phone: str, total_usd: float, items: list):
payload = {
"event_set_id": TIKTOK_EVENT_SET_ID,
"events": [
{
"event": "Purchase",
"event_id": str(order_id),
"event_time": int(time.time()),
"action_source": "offline",
"user": {
"email": sha256_hash(email),
"phone": normalize_e164_phone(phone)
},
"properties": {
"currency": "USD",
"value": float(total_usd),
"order_id": str(order_id),
"contents": items
}
}
]
}
headers = {
"Content-Type": "application/json",
"Access-Token": TIKTOK_ACCESS_TOKEN
}
response = requests.post(TIKTOK_API_URL, headers=headers, json=payload, timeout=10)
data = response.json()
if response.status_code == 200 and data.get("code") == 0:
print(f"✓ Successfully synced order {order_id} to TikTok Offline Events.")
else:
print(f"✗ Failed syncing order {order_id}: {data.get('message')}")
if __name__ == "__main__":
# Test dispatch
sample_items = [
{"content_id": "SKU-ZE-409", "content_type": "product", "quantity": 1, "price": 149.00}
]
push_offline_purchase("ORD-98214", "customer@example.com", "+14155552671", 149.00, sample_items)
3. Attribution Windows & Matching Requirements
Understanding TikTok’s attribution window limits is essential for accurate return on ad spend (ROAS) calculation:
- Maximum Upload Window: TikTok accepts offline conversion events up to 62 days after the transaction occurred. However, uploading within 24 to 48 hours is strongly recommended because Smart Bidding algorithms require fresh conversion signals to adjust real-time ad group pacing.
- Default Attribution Windows: By default, TikTok attributes conversions using a 7-day click-through and 1-day view-through window. If a customer tapped a TikTok ad 4 days before completing an in-store transaction matched by phone number, the conversion is credited.
- Match Rate Optimization: Always provide multiple user identifiers whenever possible (both
emailandphone). Providing both parameters increases TikTok’s user identity match rate by up to 34% compared to email alone.
Frequently Asked Questions (FAQs)
What is the difference between TikTok Events API and TikTok Offline Events API?
Both share the same Open API v1.3 endpoint, but they differ in configuration and scope. TikTok Events API uses a pixel_code with action_source: "website" for real-time online checkout tracking. Offline Events API uses an event_set_id with action_source: "offline" for transactions originating in retail POS, CRM sales pipelines, or call centers.
Can I test offline events without polluting live ad account reporting?
Yes. TikTok provides a “Test Events” tab inside Events Manager. By including a test_event_code parameter (e.g., TEST12345) inside your JSON payload, events are validated in real time on the screen without affecting live attribution metrics.
Editorial Disclosure: Zelobiz publishes independent engineering benchmarks and architectural evaluations. We may receive affiliate compensation when you subscribe to partner hosting services through our links at no additional cost to you.