Connect TikTok to your Shopify store with the Events API

By the HonestTag team · Published October 16, 2026

What you need

• A TikTok web pixel. TikTok's Events API setup guide says: "You must have created a pixel in the TikTok Ads Manager under Tools > Events." HonestTag needs its pixel code, an 8 to 32 character code.
• The TikTok sign-in, or an Events API access token. The Connect TikTok sign-in delivers purchases and lets HonestTag read your spend. The other route is a token you generate yourself: TikTok's guide says "you can Generate access token from pixel > Settings." That token delivers purchases but is not authorized for Reporting, so spend stays unread.
• An advertiser for spend reads (optional). After the sign-in, the card lists the advertisers it can reach.
• A paid HonestTag plan for delivery. The free Mirror does not send your orders to TikTok. You can connect on the Mirror: with the sign-in, HonestTag checks the pixel when you choose a paid plan; a pasted token is checked with one test event when you save it. Orders start going to TikTok when you choose a paid plan. See pricing.

Connect TikTok, step by step

1. Find your pixel code. In TikTok Ads Manager, go to Tools > Events and open your web pixel. Copy its pixel code. If you have no pixel yet, TikTok says to create one under Tools > Events > Connect data source > Web.
2. Sign in to TikTok. In the HonestTag app, go to Setup and click Connect TikTok on the TikTok card. Approve HonestTag on TikTok's page and you return to the card.
3. Enter the pixel code and advertiser. Under Step 1, Purchase delivery, paste the pixel code. Under Step 2, Spend reads, pick your advertiser from the list.
4. Choose the standard Purchase setting and save. Leave Also send TikTok's standard Purchase event (only if HonestTag is your ONLY TikTok Purchase source) off unless that is true, then click Save settings. On a paid plan HonestTag sends TikTok one test event to confirm the pixel.
5. Build custom conversions to optimize on. Once the HonestTag events appear, create a custom conversion from the one you want in TikTok Events Manager, mapped to the Purchase standard event, and pick it as the optimization goal of a Conversions campaign.

To use a token instead of the sign-in, open Use an Events Manager token instead on the card, paste the pixel code and the token, and save. HonestTag sends TikTok one test event with that pair first and saves nothing if TikTok refuses it. A pasted-token save also turns spend reads off for any advertiser saved before, and the card names it so you can turn them back on with the sign-in. The two authorizations are checked separately, and the card says which one needs attention.

The four purchase goals in TikTok

For each order it sends (see which orders are sent), HonestTag sends custom events to your pixel:

• HonestTag_Purchase: every order.
• HonestTag_Purchase_NC: new customers.
• HonestTag_Purchase_RC: returning customers.
• HonestTag_Purchase_FCNC: new customers whose first recorded ad click was on TikTok. See first-click attribution.

Each purchase also carries TikTok's customer_type field, new or returning. TikTok's help says custom events "are crucial for detailed reporting and audience creation, although they are not applicable for campaign optimization." To bid on a goal, make it a custom conversion. TikTok's steps: "In TikTok Ads Manager, go to Tools and click Events Manager. Click the Custom conversion tab on the left menu. Click Create custom conversion." Name it, choose your pixel as the data source and select the HonestTag event. TikTok then asks you to map a custom event to a standard event for optimization; choose Purchase. To use it, TikTok says to "Create a new campaign with the Conversions objective" and select the custom conversion "Under Optimization Goal".

HonestTag does not create these for you. TikTok's API creates a custom conversion from a custom event only when it is "configured for the App or Pixel", and TikTok does not say when an event sent from a server becomes configured. Which goal to bid on is explained in the HonestTag conversion actions.

What HonestTag sends to TikTok

For each eligible order HonestTag sends one request to TikTok's Events API for your pixel, with event source web. It holds:

• The goal events above, each with its own event ID derived from the order, the same on every retry.
• TikTok's standard Purchase event, only when you turn it on. TikTok's list of web events defines Purchase as "When a payment is completed."
• Order details: the order time, the page URL the order landed on (or your storefront address when there is none), the order value and currency, your Shopify order ID, and up to 10 products (product ID, quantity and unit price).
• Matching data: SHA-256 hashes of the buyer's email and phone, normalized as TikTok specifies (email trimmed and lowercased; phone in E.164 format with its country code, dropped when the country is unknown); a SHA-256 hash of HonestTag's random visitor ID as the external ID, when HonestTag has one for the order; the TikTok click ID (ttclid) when HonestTag's pixel recorded one; and the IP address and user agent Shopify recorded on the order.

An order with no TikTok click ID, no email and no phone is not sent. The value is the order total net of tax, and a bundle is sent as one product. Consent rules are the same as for every destination and are on the server-side delivery page. TikTok's response confirms the request was accepted, not that each event was processed. When TikTok answers with its "Partially successful" code, HonestTag records the delivery as a partial acceptance.

The card's optional switch Also send browse events (AddToCart, InitiateCheckout, AddPaymentInfo) is off by default. When on, HonestTag also sends those steps, with no order value, for visitors whose TikTok click ID (ttclid) it recorded. Each carries that click ID, a hash of the visitor ID, the IP address and the user agent. Email and phone are never sent with them. Leave it off if a pixel in your theme already sends them.

What HonestTag reads, and what it never touches

• Reads (with the sign-in and an advertiser): daily spend, clicks and impressions for the advertiser and each campaign, TikTok's own count of completed payments and their value, and the advertiser's currency and time zone. Spend appears in The Gap next to your Shopify orders.
• Writes: purchase events to your pixel, and browse events if you turn them on.
• Never touches: campaigns, ad groups, ads, budgets or custom conversions.

Avoid counting a purchase twice

TikTok's rule, from its deduplication page: "TikTok deduplicates events based on their event_source_id, event (for instance, Purchase, or AddToCart) and event_id." Its cookie-based method does not apply either: "Cookie deduplication will only drop Events API event when event_id is not set in the Events API payload", and HonestTag always sets one. HonestTag's event ID is computed on its server, so no browser pixel can send the same one.

So if Shopify's TikTok channel, or a pixel in your theme, already sends Purchase to the same pixel, turning on HonestTag's standard Purchase would count every order twice. Leave it off unless HonestTag is the only source of TikTok's standard Purchase for that pixel. The four HonestTag_Purchase events are sent whichever you choose, and their names cannot collide with any other tool's. The duplicate purchase events guide shows how to find every purchase source on a store.

Refunds, edits and which orders are sent

• Refunds: HonestTag sends TikTok no refund or retraction event. The refund is recorded in the order's proof as "refund recorded; HonestTag sends TikTok no refund or retraction event".
• Order edits and upsells: TikTok keeps the value sent at purchase time.
• Which orders: orders from your online store are sent. Point of sale orders and subscription renewals are not sent to TikTok; the first order of a subscription is an online store checkout and is sent. Orders from other apps and sales channels are kept out unless you switch them on, as described in which orders are sent.

How to check it works

1. On the card. After you save, the TikTok card shows the pixel, the advertiser, and whether browse events and the standard Purchase are on.
2. In HonestTag order proof. After the next online order, open it in the HonestTag app. The proof shows TikTok as the platform, the delivery status, the event ID and which events were sent, for example HonestTag_Purchase and HonestTag_Purchase_NC.
3. In TikTok Events Manager. TikTok says to "navigate to your pixel's detail page", where the Server metric "shows the distinct events received only from the Events API."

Error messages and what to do

• "Pixel code must be the 8-32 character code from TikTok Events Manager." Copy the pixel code again from Tools > Events.
• "paste the Events API access token exactly as TikTok shows it". The pasted token was empty or had a space or line break in it.
• "TikTok did not accept the token for pixel ... Nothing was saved; regenerate the token in Events Manager and try again". The token and the pixel code do not belong together, or the token was revoked. TikTok's reason is in the parentheses before "Nothing was saved".
• "Saved, but TikTok did not accept a test event for pixel ...". The settings are saved, but the pixel code is wrong or the connected login cannot reach that pixel.
• "Advertiser ID must contain only digits." Pick the advertiser from the list, or type its numeric ID.
• "the stored TikTok token is not authorized for Reporting on this advertiser". Spend reads need the TikTok sign-in on an advertiser that login can reach. Purchases still deliver.
• Reconnect needed. TikTok answered that the token has no permission, has expired, is empty or is invalid (its codes 40001, 40102, 40104 and 40105). Click Reconnect TikTok on the card, or paste a new token.

Disconnecting

Disconnect from the TikTok card, or uninstall the app. Delivery and spend reads stop at once and the stored token is deleted. Everything already measured stays, per the published retention schedule. Moving from another tracking app is covered in switching apps.

Frequently asked questions