🎯 Why Use TikTok CAPI?

TikTok Conversion API allows you to:

• Track conversions even when users block cookies or JavaScript
• Improve ad performance and ROAS
• Deduplicate server and browser events with event_id
• Enable event matching with hashed user data (like email)

---

🧰 Requirements

Tool	Purpose
TikTok Pixel	To link browser and server events
TikTok Events API Token	For authenticating CAPI requests
Google Tag Manager Web + Server Containers	For client-server event flow
Access to osCommerce	Inject dataLayer and PHP
Cloud hosting (App Engine or Cloud Run)	Host sGTM

---

🧱 Step-by-Step Implementation

---

🔹 1. Create TikTok Events API Access

1. Go to TikTok Events Manager
2. Select your Pixel
3. Click on “Set up manually via Events API”
4. Note down:
   • Access Token
   • Pixel ID

---

🔹 2. Set Up GTM Server Container (if not already done)

• Create Server container in GTM
• Deploy to GCP:

gcloud app deploy

Note your endpoint: https://gtm.yourstore.com

🔹 3. Inject Purchase Data into dataLayer in checkout_success.php

<?php
$order_query = tep_db_query("SELECT orders_id, order_total, customers_email_address FROM " . TABLE_ORDERS . " WHERE customers_id = '" . (int)$customer_id . "' ORDER BY orders_id DESC LIMIT 1");
$order = tep_db_fetch_array($order_query);
$order_id = $order['orders_id'];
$order_total = $order['order_total'];
$customer_email = $order['customers_email_address'];
$event_id = bin2hex(random_bytes(16));
?>
<script>
window.dataLayer = window.dataLayer || [];
dataLayer.push({
  event: 'purchase',
  transaction_id: '<?= $order_id ?>',
  value: <?= $order_total ?>,
  currency: 'USD',
  email: '<?= $customer_email ?>',
  event_id: '<?= $event_id ?>'
});
</script>

🔹 4. GTM Web Container – HTTP Request Tag to Server

a. Trigger:

• Custom Event = purchase

b. Tag Type: HTTP Request

• URL: https://gtm.yourstore.com/collect
• Method: POST
• Body:

{
  "event_name": "Purchase",
  "event_id": "{{DLV - event_id}}",
  "transaction_id": "{{DLV - transaction_id}}",
  "value": {{DLV - value}},
  "currency": "{{DLV - currency}}",
  "email": "{{DLV - email}}",
  "user_agent": "{{User-Agent}}",
  "ip_override": "{{Client IP}}"
}

🔹 5. GTM Server Container – TikTok CAPI Tag

a. Variables Needed in sGTM:

• event_name
• event_id
• transaction_id
• value
• currency
• email
• user_agent
• ip_override

---

b. Create Custom Template for TikTok CAPI in sGTM

const sendHttpRequest = require('sendHttpRequest');
const log = require('logToConsole');
const JSON = require('JSON');

// TikTok Pixel Info
const access_token = 'YOUR_TIKTOK_ACCESS_TOKEN';
const pixel_id = 'YOUR_TIKTOK_PIXEL_ID';

// Gather Event Data
const payload = {
  pixel_code: pixel_id,
  event: data.event_name,
  event_id: data.event_id,
  timestamp: new Date().toISOString(),
  context: {
    ad: {},
    page: {},
    user: {
      email: [sha256(data.email.trim().toLowerCase())],
      ip: data.ip_override,
      user_agent: data.user_agent
    }
  },
  properties: {
    value: data.value,
    currency: data.currency,
    order_id: data.transaction_id
  }
};

// Send to TikTok CAPI
sendHttpRequest(
  'https://business-api.tiktok.com/open_api/v1.2/pixel/track/',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Access-Token': access_token
    }
  },
  JSON.stringify(payload)
);

log("✅ TikTok CAPI Event Sent: " + data.event_name);

🔹 6. Add SHA256 Email Hashing Utility

If your template doesn’t support built-in hashing, add:

function sha256(str) {
  return Utilities.computeDigest(
    Utilities.DigestAlgorithm.SHA_256,
    str,
    Utilities.Charset.UTF_8
  ).map(b => ('0' + (b & 0xFF).toString(16)).slice(-2)).join('');
}

🔹 7. Validate CAPI Events

1. Go to TikTok Ads Manager > Events Manager
2. Select your Pixel
3. Go to Test Events
4. Trigger a test purchase on your site
5. Look for event_id and verify matched events

🧠 Best Practices for Attribution Accuracy

Technique	Description
🔁 Use event_id	Deduplicate between browser & CAPI
🔐 Hash PII	Hash email addresses with SHA256
📡 Include IP/User Agent	Boost event match quality
🎯 Use consistent Pixel ID	Link all data to the same source
✅ Fire events only on confirmed orders	Prevent false tracking

---

🔄 Optional: Add Client-Side Pixel Tag for Deduplication

In GTM Web:

<script>
ttq.track('CompletePayment', {
  value: {{DLV - value}},
  currency: '{{DLV - currency}}',
  order_id: '{{DLV - transaction_id}}',
  event_id: '{{DLV - event_id}}'
});
</script>

Both Pixel and CAPI will send the same event_id, allowing TikTok to deduplicate automatically.

---

✅ Summary

Step	Action
1	Get TikTok Pixel ID + Access Token
2	Add dataLayer to osCommerce
3	Fire Pixel + forward data to sGTM
4	Send deduplicated events via TikTok CAPI
5	Hash emails, include IP & user agent
6	Validate in TikTok Events Manager