How to Track TikTok Ads Conversions with Offline Events API (Step-by-Step Setup)

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 email and phone). 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.


Mamun Hossain

Mamun Hossain

Systems Architect

Founder of Zelobiz & Enterprise Infrastructure Architect. Specializing in autonomous software engineering workflows, server-side tracking pipelines, and high-performance self-hosted infrastructure.

✓ 100% Independent Technical Evaluation ✓ Benchmarked on Dedicated Hardware Follow Zelo Biz on Facebook ↗

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.