TikTok Offline Events API
Overview
Section titled “Overview”The TikTok Offline Events API reports conversions that happened away from your website: in-store purchases, phone orders, bookings and outcomes recorded in a CRM. TikTok uses them to attribute conversions to your campaigns and to optimize delivery.
Use this destination when the conversion lives in a system Signals can read, such as a CRM, a file drop, a database or a warehouse.
Supported sources
Section titled “Supported sources”Sources supported by TikTok Offline Events API
| Category | Supported |
|---|---|
| API | |
| CRM | |
| Database | |
| File & storage | |
| Warehouse |
Prerequisites
Section titled “Prerequisites”Before connecting TikTok Offline Events API, make sure you have:
- An active TikTok Ads account.
- Server-side API access permissions, if you plan to connect manually.
- An offline event set created in TikTok Events Manager, as described below.
- A Datahash Studio account with the target project selected.
- A source connected in the same project. The identifiers and event details TikTok receives come from that source mapping, not from this destination.
Offline events go to an event set configured to receive them, not to your web pixel. Create one before you connect.
- In TikTok Ads Manager, open Tools, then Events.
- Choose Offline Events and select Manage.
- Create the event set, then open Settings and generate an access token if you intend to connect manually.
Authentication
Section titled “Authentication”In Studio, open Destinations, find TikTok, and click the Offline Events API tile. You can connect in two ways.
Single sign-on
Section titled “Single sign-on”- Click Continue with TikTok and sign in with your TikTok for Business credentials.
- Approve the requested permissions.
- Select the Advertiser ID and the associated Event Set ID that events should be written to.
- Click Finish.
Manual setup
Section titled “Manual setup”- Enter your Pixel ID and Access Token.
- Click Validate Credentials, then Finish.
TikTok calls the same asset an Event Set on the single sign-on screen and a Pixel on the manual screen. They refer to the same thing.
Manage instance
Section titled “Manage instance”To change the instance, open it from Manage Instances, use the menu in the top right and choose Edit, update the fields and click Finish. Cancel keeps the previous configuration running, so updates apply only after you finish.
Deduplication
Section titled “Deduplication”Deduplication happens on the basis of the event ID. Map a stable value from your source, such as a transaction ID, so re-reading a file does not report the same conversion again.
The event ID is set by the source mapping, not here.
Data & identifiers
Section titled “Data & identifiers”Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach TikTok.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Event time | Always. UNIX timestamp. Use the time of the conversion, not the time of upload. |
| Event name | Always. |
| Last modified date | Always. |
| Action source | Always. Where the conversion happened. |
| Email address | One of email address or phone number. |
| Phone number | One of email address or phone number. Up to three values. |
| Currency | Purchase events only. The three-letter currency code. |
| Value | Purchase events only. |
Optional
Section titled “Optional”| Field | Notes |
|---|---|
| Additional email addresses | Up to two more, one address each. |
| Transaction ID | A stable reference for the conversion. Map it if you have one; it is what deduplication depends on. |
| Product detail | Type, name, category, IDs, brand, price and quantity. |
| Shop ID | Identifies the shop the conversion belongs to. |
| Number of items | How many items the conversion covered. |
TikTok does not use name or location fields on offline events, so the match depends on email and phone. Send both where you have them.
Consent parameters
Section titled “Consent parameters”TikTok exposes a Limited Data Usage control on this connector. Select Yes to enable the restriction on how TikTok uses the data, which TikTok cites as relevant to United States state privacy laws in California, Virginia, Colorado, Connecticut and Utah. Select No to disable it.
This applies to the whole instance rather than to individual events, so decide it deliberately rather than leaving the default.
Best practices
Section titled “Best practices”- Send email and phone together.
- Map a stable transaction ID, or a re-read file will count every conversion again.
- Use the conversion time as the event time rather than the upload time, or TikTok will attribute against the wrong window.
- Decide the Limited Data Usage setting deliberately rather than accepting the default.
- Keep formatting clean at source: lowercase email, phone with country code, no stray whitespace.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Validate Credentials fails. Re-check the Pixel ID and confirm the token was generated for that event set and has server-side API access.
No event sets listed after signing in. No offline event set exists yet, or the authenticated user cannot see it. Create one in Events Manager first.
No events appearing in Events Manager. Confirm a source is connected in the same project and sending, and that you selected the offline event set rather than the web pixel.
Duplicate conversions. The transaction ID is missing or changes between exports.
Low match rates. Add phone numbers where you only have email. Name and location will not help on this connector.
Delivery stopped. The access token may have expired or been revoked. Generate a new one and revalidate.