TikTok integration

This guide applies only when selling pre-orders through Purple Dot's own checkout. Pre-orders sold through the Shopify checkout benefit from the same tracking as your regular sales.

If you have enabled TikTok tracking on the Integration settings page in the Merchant Portal, the Purple Dot checkout automatically sends certain events to TikTok via the Events API.

What you need before you start

• The TikTok app installed on the Shopify store and connected to the merchant’s TikTok Ads account

• A TikTok Pixel active on the storefront via that app, with browser events flowing in TikTok Events Manager

• Admin access to the merchant’s TikTok Ads Manager / Events Manager

Step 1 - Install the TikTok app on Shopify

1. In Shopify Admin, go to Settings → Apps and sales channels (or open the TikTok app on the Shopify App Store).

2. Install TikTok (by TikTok Inc.).

3. Open the app and sign in with the TikTok account that has access to the merchant’s TikTok Ads Manager.

4. Connect the Shopify store to the correct TikTok Ads account.

5. When prompted, set up or connect a TikTok Pixel. The app supports one-click pixel integration — use the same pixel you plan to use for Events API and Purple Dot.

6. Complete the app setup and confirm the pixel is connected and active on the storefront.

Use the same pixel everywhere. The Pixel ID you enter in Purple Dot must match the pixel connected in the TikTok Shopify app and shown in TikTok Events Manager. If these don’t match, connection tests may pass but production events will go to the wrong pixel—or checkout events won’t attribute correctly.

Verify the pixel is working on the storefront

1. In Shopify Admin, go to Settings → Customer events

2. Verify the app is “Connected”

3. On the TikTok app, click “Test”

1. Accept any cookie consent banner that covers marketing/analytics cookies

2. Confirm events are being processed

After the connection is saved, Purple Dot will send real server events automatically when a TikTok connection exists for the store. No extra configuration is required in Purple Dot beyond saving the connection

Checkout / preorder action	TikTok event name
Add to cart	AddToCart
Initiate checkout	InitiateCheckout
Add payment info	AddPaymentInfo
Pre-order created	Purchase

Step 2 - Generate an access token, get the Pixel ID, and open Test Events

Generate an access token

1. In Events Manager, on the same pixel, go to Settings → Events API.

2. Generate a new access token

3. Copy the token immediately and store it securely.

This token is what Purple Dot calls Access Token.

Find the Pixel ID

1. Stay on the pixel in Events Manager.

2. Open Settings (or the pixel overview).

3. Copy the Pixel ID (alphanumeric string).

Use this value in Purple Dot’s Pixel ID field.

Open Test Events (for verification)

1. In Events Manager, select the pixel.

2. Open the Test Events tab (or Test event section).

3. Copy the Test event code shown there. You’ll use this when testing from Purple Dot or on the storefront so events appear in this tab instead of production reporting.

Keep this tab open while you run any of the verification options in Step 3.

Step 3 - Add credentials in Purple Dot

1. Log in to the Purple Dot merchant portal.

2. Go to Settings → Integrations.

3. Under Analytics, click Connect for TikTok.

4. In the TikTok connection modal, enter:

   Field	Value
   Access Token	Token from Step 2
   Pixel ID	Pixel ID from Step 2
   Test Event Code (optional)	Test event code from the Test Events tab

5. Click Save.

Step 4 - Verify the connection

There are two ways to verify the integration. Use Option A for a quick credential check, Option B to test the full checkout flow end-to-end.

Option A - Test Connection in the modal (recommended for first setup)

1. In the TikTok connection modal, fill in Access Token, Pixel ID, and Test Event Code.

2. Click Test Connection (bottom-left of the modal).

3. Wait for “Credentials verified!”

Purple Dot sends a dedicated test event:

• Event name: PurpleDotTestEvent

• External ID: purple-dot-connection-test (hashed)

If a Test Event Code was provided, TikTok routes the event to the Test Events tab.

Option B - Test via live checkout with tiktok_test_event_code (end-to-end)

This option verifies the full integration: storefront → Purple Dot checkout → TikTok Events API → Events Manager Test Events. It is the best way to confirm real checkout events (AddToCart, InitiateCheckout, AddPaymentInfo, Purchase) are flowing correctly.

1. Copy the Test event code from TikTok Events Manager → [your pixel] → Test Events.

2. Open the storefront with the test event code in the URL:

   https://your-store.com/products/example-product?tiktok_test_event_code=YOUR_TEST_CODE

   Replace YOUR_TEST_CODE with your actual test event code. The parameter can be added to any storefront page URL.

3. Accept cookie consent so the _ttp cookie is set.

4. Complete a test preorder/checkout flow (add to cart, open checkout, enter payment details, complete the order).

5. In TikTok Events Manager → Test Events, confirm the real checkout events appear — for example AddToCart, InitiateCheckout, AddPaymentInfo, and Purchase.

How it works

• Purple Dot reads tiktok_test_event_code from the storefront URL.

• The code is stored for the browser session (until the tab is closed), so it persists as the shopper navigates and opens embedded checkout.

• For that session, all TikTok server events sent by Purple Dot include the test event code and appear in the Test Events tab rather than production reporting.

Tip: To stop sending test events, close the browser tab (or open a new session without the query parameter). The test event code is not persisted beyond the browser session.