> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upstackdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Events API

> Send conversion events to TikTok via the Events API for campaign optimization, audience building, and attribution — powered by Upstack Signal.

<Note>
  **Data direction:** This is a **destination** — Upstack sends event and conversion data **out** to this platform via server-side APIs.
</Note>

## What it does

TikTok's Events API is the server-side counterpart to the TikTok Pixel. Upstack Signal forwards storefront events — page views, product views, add-to-carts, checkouts, and purchases — directly to TikTok's servers, bypassing browser restrictions like ad blockers, ITP, and cookie limits.

Server-side delivery gives TikTok's algorithm a fuller picture of the conversions your ads actually drove, which improves campaign optimization, audience modeling, and attribution accuracy. Match rates from server-side events are consistently higher than browser-only tracking because each event carries hashed customer data and the `ttclid` click identifier when available.

<Note>
  Unlike Meta and Google Ads, TikTok uses **token-based auth** instead of OAuth. You'll paste a Pixel ID and an Events API access token into the Upstack destination — there is no OAuth handshake to step through.
</Note>

## How it works

Upstack runs as a dual-tracking layer alongside the TikTok Pixel. The Upstack Pixel captures events in the browser and forwards each event to Upstack's edge infrastructure, where it is hashed, enriched with identity and click-ID data, and sent to the TikTok Events API as a server-side event with a shared `event_id`.

TikTok deduplicates server events against matching browser Pixel events using that `event_id`, so you do not double-count conversions as long as both sources use the same Pixel ID. PII (`email`, `phone`, `external_id`) is hashed with SHA-256 before delivery, as required by the Events API.

## Setup guides

<CardGroup cols={2}>
  <Card title="Onboarding guide" icon="route" href="/guides/tiktok-ads/complete-how-to-guide-for-onboarding-tiktok-ads-in-upstack-data">
    End-to-end walkthrough for connecting TikTok to Upstack Data.
  </Card>

  <Card title="Configure pixel destination" icon="sliders" href="/guides/tiktok-ads/how-to-configure-tiktok-ads-pixel-destination-in-upstack-data">
    Configure the TikTok Pixel destination inside Upstack Data.
  </Card>

  <Card title="Find Pixel ID" icon="magnifying-glass" href="/guides/tiktok-ads/how-to-find-your-tiktok-ads-pixel-id">
    Locate your existing TikTok Pixel ID in Events Manager.
  </Card>

  <Card title="Create Pixel ID" icon="plus" href="/guides/tiktok-ads/how-to-create-new-tiktok-ads-pixel-id">
    Create a new TikTok Pixel for your store.
  </Card>

  <Card title="Generate API token" icon="key" href="/guides/tiktok-ads/how-to-generate-your-tiktok-api-access-token">
    Generate the Events API access token Upstack uses to send events.
  </Card>

  <Card title="Disable Shopify TikTok data sharing" icon="ban" href="/guides/tiktok-ads/how-to-disable-tiktok-data-sharing-in-shopify">
    Turn off Shopify's native TikTok integration to prevent duplicate events.
  </Card>
</CardGroup>

## Event mapping

Upstack maps storefront events to TikTok standard events automatically:

| Upstack event      | TikTok event       | Key parameters                                    | Notes                                                  |
| ------------------ | ------------------ | ------------------------------------------------- | ------------------------------------------------------ |
| `PageView`         | `ViewContent`      | `url`, `referrer`                                 | TikTok has no generic PageView — mapped to ViewContent |
| `ViewContent`      | `ViewContent`      | `content_id`, `content_type`, `value`, `currency` | Product page views                                     |
| `AddToCart`        | `AddToCart`        | `content_id`, `content_type`, `value`, `currency` | Cart additions with product details                    |
| `InitiateCheckout` | `InitiateCheckout` | `value`, `currency`, `quantity`                   | Checkout started                                       |
| `Purchase`         | `CompletePayment`  | `content_id`, `value`, `currency`, `order_id`     | Completed orders with revenue                          |

Every event includes user data parameters (`email`, `phone`, `external_id`) when available, hashed with SHA-256. TikTok click IDs (`ttclid`) captured by the Upstack Pixel are included for deterministic matching.

## FAQ

<AccordionGroup>
  <Accordion title="How do I know events are reaching TikTok?">
    Open TikTok Events Manager, select your Pixel, and check the **Overview** and **Test Events** tabs. Server-side events appear with a "Server" source badge, typically within 5–10 minutes of storefront activity. Upstack also surfaces delivery status inside the destination settings.
  </Accordion>

  <Accordion title="Will I see duplicate conversions if I run both the TikTok Pixel and the Events API?">
    No — as long as the Pixel ID in Upstack matches the Pixel ID firing in your storefront's TikTok browser Pixel (`ttq.load`). Upstack sends a shared `event_id` on every server-side event, and TikTok's deduplication logic matches events by `event_id` and keeps only one. If you see duplicates, the Pixel IDs almost always differ between the two sources.
  </Accordion>

  <Accordion title="What if my event match rate is low?">
    TikTok's match rate depends on how much identity data each event carries. Common causes of low match quality:

    * **Missing `ttclid`** — TikTok ads should link directly to your storefront so the click ID lands in the URL and is captured by the Upstack Pixel.
    * **Anonymous visitors** — events from visitors without email or phone have fewer keys to match against. Match rates improve as more identified customers convert.
    * **Missing checkout fields** — make sure your Shopify checkout collects email and phone; both are strong server-side match keys.
  </Accordion>

  <Accordion title="Do I need to disable Shopify's native TikTok integration?">
    Yes — if Shopify is also sending events to the same TikTok Pixel, you'll see duplicates that TikTok cannot deduplicate (Shopify does not emit a matching `event_id`). Follow the guide above to disable TikTok data sharing in Shopify before activating Upstack's TikTok destination.
  </Accordion>

  <Accordion title="Can I send only specific event types to TikTok?">
    Yes. Each destination supports event filtering — you can choose to forward only purchases, only standard events, or any custom subset. Excluded events are dropped at the Upstack level and are not retried.
  </Accordion>
</AccordionGroup>

## Advanced configuration

<Accordion title="TikTok Shop orders">
  If you sell through TikTok Shop, those orders flow into Shopify as fulfilled orders. Upstack processes them like any other Shopify order, which means they get sent to all your active destinations — including Meta.

  **Should you exclude TikTok Shop orders from other destinations?**

  Upstack gives you the option via **Settings → Order Source Exclusions**, where you can block orders by source. However, sending TikTok Shop orders to Meta is generally beneficial — more conversion data helps Meta's algorithm find similar high-value customers, regardless of where the original purchase happened.

  If you still want to exclude them:

  1. Go to **Upstack → Settings → Order Source Exclusions**.
  2. Add TikTok Shop as a blocked source.
  3. Orders originating from TikTok Shop will no longer fire to other destinations.
</Accordion>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Events not appearing in TikTok Events Manager">
    If events aren't appearing after 10 minutes of confirmed store traffic, check the basics first.

    **Steps to fix:**

    1. Go to **Integrations → Destinations → TikTok**
    2. Verify the **Pixel ID** and **Access Token** are correct (no extra spaces or truncated characters)
    3. Confirm the destination status is Active (green)
    4. If the token was revoked or expired, generate a new one in TikTok Business Center and update the destination
  </Accordion>

  <Accordion title="Duplicate conversions in TikTok">
    If you see inflated conversion counts, another TikTok event source is likely still active.

    **Steps to fix:**

    1. Check for the TikTok Shopify sales channel — disable its data sharing / pixel component
    2. Look for third-party pixel apps (Omega, Mega TikTok Pixel) and uninstall them
    3. Inspect your theme code for manual TikTok pixel snippets in the `<head>` section
    4. After removing duplicate sources, monitor TikTok Events Manager for 24 hours to confirm counts normalize
  </Accordion>

  <Accordion title="Low match quality scores">
    TikTok's match quality measures how well server events match to TikTok users.

    **Common causes:**

    * **High anonymous traffic** — Events from visitors who haven't logged in or provided contact info have fewer matching parameters. Match quality improves as more identified customers generate events.
    * **Incorrect pixel ID** — If the pixel ID doesn't match the one associated with your ad account, events arrive but can't be matched to campaign data.

    Match quality typically improves over 1–2 weeks as Upstack's identity resolution builds visitor profiles.
  </Accordion>
</AccordionGroup>

<Note>
  For additional troubleshooting beyond TikTok-specific issues, see [Troubleshooting: Events Not Reaching Destination](/troubleshooting/events-not-reaching-destination).
</Note>

## Related

<CardGroup cols={2}>
  <Card title="Conversion API forwarding" icon="lightbulb" href="/concepts/conversion-api-forwarding">
    How Upstack Signal forwards events to ad platforms via server-to-server APIs.
  </Card>

  <Card title="Identity resolution" icon="fingerprint" href="/concepts/identity-resolution">
    How Upstack matches anonymous visitors to known customers for higher match rates.
  </Card>

  <Card title="Meta CAPI destination" icon="meta" href="/destinations/meta-capi">
    Set up Meta's Conversions API as another server-side destination alongside TikTok.
  </Card>

  <Card title="Events not reaching destination" icon="wrench" href="/troubleshooting/events-not-reaching-destination">
    End-to-end diagnostic guide when events aren't arriving at any destination.
  </Card>
</CardGroup>