TikTok Events API for Shopify: setup and deduplication

The TikTok Events API is TikTok's server-to-server connection for conversion data. Instead of relying only on the TikTok pixel in the shopper's browser, your store, or a tool such as ROASaurus, sends events like purchases straight to TikTok. TikTok recommends running the Events API next to the pixel and deduplicating the two with a shared event_id.

This guide covers what the Events API sends from a Shopify store, the Purchase and CompletePayment event names, the click id and cookie TikTok matches on, how deduplication works, how to test in TikTok Events Manager, and how to set it all up in ROASaurus.

What is the TikTok Events API?

The TikTok pixel is a script on your store. It fires events from the shopper's browser, so it only counts what happens while the script loads and runs. An ad blocker, a script error or a shopper who closes the tab before the order confirmation loads can all stop it.

The Events API sends the same kind of event from a server. On Shopify, the most dependable record of a purchase is the order itself. Shopify reports every paid order by webhook, whether or not the browser script ran. That is the idea behind server-side tracking on Shopify.

The two are not alternatives. TikTok's advice is to share events through both, keep them consistent along the shopping journey, and let TikTok remove the duplicates.

Which events does ROASaurus send to TikTok?

Four moments in a Shopify store matter for TikTok's optimization: a product view, an add to cart, the start of checkout and the purchase. ROASaurus sends all four to the Events API and fires the same four through the TikTok pixel, with the same event ids. Page views go through the pixel only.

In the pixel settings you can untick server events you do not want to send, and add filters such as a country or a minimum order value.

Purchase or CompletePayment?

TikTok renamed its purchase event. The current name is Purchase. The old name, CompletePayment, still works: TikTok converts legacy names on its side, shows them under the new name in reporting, audiences and optimization, and says CompletePayment will be supported indefinitely. TikTok asks new pixel setups to use Purchase.

ROASaurus sends CompletePayment, in the pixel and in the Events API. In TikTok Events Manager and Ads Manager, those events show as Purchase. For deduplication, what counts is that both copies of a purchase use the same event name, and they do.

How does TikTok match an event to a shopper?

An event only helps your campaigns if TikTok can link it to the person who saw or clicked the ad. TikTok calls these identifiers match keys, and its Events API guide asks you to pass back all relevant match keys to increase match rates. Events Manager shows the result as an Event Match Quality score, a weighted average of how often each match key is present.

TikTok notes that the pixel shares the IP address and user agent by default, but the Events API needs them added by hand. ROASaurus takes them from the shopper's checkout session, or from the order if there was no session. Two other keys need attention on Shopify.

ttclid: the TikTok click id

When a shopper clicks a TikTok ad, TikTok adds ttclid to the landing page URL. If your store does not save it on that first page, it is gone by the time the order arrives, several pages later. ROASaurus reads ttclid on the landing page, stores it with the visitor id, writes it to the Shopify cart, and adds it to the server event when the order comes in.

_ttp: the pixel cookie

The _ttp cookie is a first-party cookie that the TikTok pixel uses on your domain. ROASaurus reads it on the storefront and in checkout and sends it as ttp in the server event. It is one more reason to keep the pixel running next to the Events API.

{
  "event_source": "web",
  "event_source_id": "CXXXXXXXXXXXXXXXXXXX",
  "data": [{
    "event": "CompletePayment",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "user": {
      "email": "a3f1…9c2e",
      "phone": "7b40…11d8",
      "external_id": "e05c…4a7f",
      "ttclid": "E.C.P.v3…",
      "ttp": "2Xb7…",
      "ip": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (iPhone; …)"
    },
    "page": { "url": "https://example-store.com/checkouts/…/thank-you" },
    "properties": {
      "currency": "USD",
      "value": 84,
      "content_type": "product",
      "contents": [{ "content_id": "44123456789", "content_name": "Linen shirt", "quantity": 2, "price": 42 }],
      "order_id": "5512345678901"
    }
  }]
}

How does deduplication work?

When the pixel and the Events API both report the same purchase, TikTok receives two events for one order. To keep only one, TikTok needs two values to be identical in both copies: the event name and the event_id. TikTok then records the first copy it receives for measurement and reporting, so the order counts once. This works for matching copies that arrive within a 48-hour window from the first one.

ROASaurus builds the event id for a purchase from the Shopify order id. The purchase from order 5512345678901 has the event id order-5512345678901, in the checkout pixel and on the server. Storefront events, such as product views and adds to cart, get a random id when they happen, and the browser copy and the server copy share it.

Here is what that means for the numbers. Take an example store with 200 orders in a week. The pixel fires for 150 of them. The other 50 shoppers used an ad blocker, declined marketing cookies or left before the confirmation page loaded. The Events API sends all 200.

The 350 is the number to worry about. It would make TikTok's purchase count, and the ROAS based on it, 75% higher than reality, because 350 ÷ 200 = 1.75. TikTok also uses these events for optimization and targeting, so its bidding would learn from 150 purchases that did not happen.

Why do purchases get counted twice on Shopify?

Double counting happens when TikTok receives two copies of a purchase that it cannot match. Check these causes before you trust a jump in TikTok purchases:

• Two tools send the same pixel. The TikTok sales channel app on Shopify can also send events for your pixel. Its event ids do not match the ids ROASaurus uses, so TikTok counts each order twice. Disconnect the pixel in that app.
• The pixel is also in your theme code. A pixel snippet pasted into the theme fires its own events without your event ids. Remove it and let one tool load the pixel.
• One side has no event_id. A server purchase without an event_id, or with a new random id, cannot be matched to the pixel copy.
• The event names differ. TikTok deduplicates only identical events. Both copies of a purchase must use the same event name.

The help article on double counting walks through the same checks for Meta and the other platforms.

How do you test the Events API in TikTok Events Manager?

TikTok Events Manager has a Test events tab for both browser and server events. Use it before you rely on the data:

1. Copy a test event code

   In TikTok Events Manager, open your pixel and go to Test events. Copy the test event code.

2. Paste it in ROASaurus

   Open Tracking & platforms, edit the TikTok pixel and paste the code in the Test event code field. Server events now carry it.

3. Place a test order

   Visit your store, view a product, add it to the cart and complete an order.

4. Check both sides

   In Test events, filter on browser and on server events. You should see the purchase from both. In ROASaurus, the Event log shows each server delivery as sent or failed.

5. Remove the test code

   Delete the test event code when you are done, so your live server events are no longer sent as test events.

TikTok can answer a request with HTTP 200 and still reject the event, with an error code in the response body. ROASaurus reads that code, so a rejected event shows as failed in the Event log instead of passing silently.

After a day of live traffic, open the pixel's overview in Events Manager. It lists each event with its connection method, Event Match Quality score and when it was last received. The event details include matching and deduplication information, and Diagnostics lists quality issues with guidance on how to fix them.

How to set up the TikTok Events API on Shopify with ROASaurus

You need a Shopify store with the ROASaurus app and access to TikTok Events Manager. The TikTok integration page lists every field ROASaurus sends.

1. Connect your Shopify store

   Go to Add a store › Shopify, click Install app and switch on the ROASaurus app embed in the theme editor. The embed captures ttclid and the _ttp cookie on every page. The Shopify setup guide shows each step.

2. Add the checkout pixel

   In Shopify admin › Settings › Customer events, add a custom pixel named ROASaurus and paste the snippet from your Tracking & platforms page. It fires the TikTok pixel in checkout, including the browser copy of the purchase.

3. Create an access token

   In TikTok Events Manager, open your pixel and generate an Events API access token in its settings. Copy the token and the pixel code.

4. Add the TikTok pixel in ROASaurus

   Go to Tracking & platforms, click Add pixel on the TikTok card and fill in Pixel code and Events API access token. Keep Also load the browser pixel (recommended, deduplicated) ticked, so browser and server events share ids.

5. Add spend (optional)

   Fill in Advertiser ID for spend and a Marketing API token. ROASaurus then imports TikTok spend, so TikTok campaigns show ROAS and CPA next to your other channels.

6. Test, then go live

   Send a test order with a test event code as described above, then remove the code.

With Respect visitor consent on, which is the default, ROASaurus follows the shopper's choice in Shopify's cookie banner. When a shopper declines marketing cookies, ROASaurus does not load the TikTok pixel for them, sets no visitor id, so their clicks are not linked to them, and does not send their browsing events to TikTok. Their paid order is still sent to the Events API from the server, with hashed order data and the order's IP address and user agent, but without ttclid or _ttp. The consent and privacy guide explains what is stored and sent.

With spend synced, TikTok campaigns appear in attribution reports next to Meta, and creative analytics adds TikTok's video stats per ad. ROASaurus credits orders to the ad clicks and UTMs it recorded, and counts view-through conversions only as a modelled estimate in its Clicks & views model, so its totals usually differ from TikTok Ads Manager. For the other server-side platforms, see the Pinterest Conversions API guide and the Meta Conversions API guide.

Sources

1. TikTok For Business: About Events API
2. TikTok Ads Manager: About Event Deduplication
3. TikTok Ads Manager: How to Adopt TikTok's Updated Standard Events
4. TikTok Ads Manager: How to set up matching events with Events API
5. TikTok Ads Manager: About diagnostic and monitoring tools in TikTok Events Manager

In ROASaurus

• TikTok integration
• Server-side tracking in ROASaurus
• Help: prevent double counting
• Help: set up ROASaurus on Shopify

Keep reading