TikTok Events API integration

What you can sync

Conversion events: Complete funnel tracking from ViewContent to CompletePayment
Standard events: User engagement, navigation, and interaction tracking
Custom events: Any business-specific events you want to track
Audiences: Sync audience membership for custom audience targeting

Prerequisites

A TikTok Ads account
A TikTok Pixel installed on your website or app
A Pixel Code (format: C9XXXXXXXXXXXXXXXXXX)
An Access Token for TikTok Events API

You can find your Pixel Code in TikTok Ads Manager under Assets → Events → Web Events → Manage. Generate an Access Token under Tools → Events Manager → Settings → Generate Access Token.

Event types

TikTok Events API supports standard conversion events that Masivo automatically maps and transforms:

Standard conversion events (14 events)

These events track the complete customer journey and optimize your TikTok ad campaigns:

Event	When to send	Key parameters	Masivo mapping	How to send
`ViewContent`	User views a product or page	`contents`, `content_type`, `value`	`view_item`	Auto-mapped
`ClickButton`	User clicks a button	`contents`, `description`	—	Use `"ClickButton"`
`Search`	User performs a search	`query`, `contents`	`search`	Auto-mapped
`Contact`	User initiates contact	`description`	—	Use `"Contact"`
`Download`	User downloads content	`contents`, `description`	—	Use `"Download"`
`SubmitForm`	User submits a form	`contents`, `description`	—	Use `"SubmitForm"`
`CompleteRegistration`	User creates an account	`contents`, `value`	`sign_up`	Auto-mapped
`Subscribe`	User subscribes to service	`contents`, `value`	—	Use `"Subscribe"`
`AddToWishlist`	User adds item to wishlist	`contents`, `value`, `currency`	`add_to_wishlist`	Auto-mapped
`AddToCart`	User adds item to cart	`contents`, `value`, `currency`	`add_to_cart`	Auto-mapped
`InitiateCheckout`	User starts checkout process	`contents`, `value`, `currency`	`begin_checkout`	Auto-mapped
`AddPaymentInfo`	User adds payment information	`contents`, `value`, `currency`	`add_payment_info`	Auto-mapped
`PlaceAnOrder`	User places an order	`contents`, `value`, `currency`	—	Use `"PlaceAnOrder"`
`CompletePayment`	User completes a purchase	`contents`, `value`, `currency`, `order_id`	`PURCHASE`	Auto-mapped

Auto-mapped events: Masivo automatically converts common event names (like purchase or add_to_cart) to TikTok’s standard names. Use exact name events: For events marked with “Use EventName”, send that exact TikTok event name in the type field.

Custom events

Events not in the table above are sent as truly custom events with flattened parameters prefixed with custom_. Example of a custom event:

{
  "type": "video_watched_50",
  "customer_id": "cust_123",
  "video_id": "vid_789",
  "duration_seconds": 120
}

This becomes a custom event in TikTok with parameters: custom_video_id, custom_duration_seconds.

Configuration

Step 1: Get your TikTok credentials

Log in to TikTok Ads Manager
Navigate to Assets → Events → Web Events
Select your Pixel or create a new one
Copy your Pixel Code (starts with C9)
Go to Settings → Generate Access Token
Copy the generated Access Token

Keep your Access Token secure. It provides access to send events to your TikTok Pixel. Never share it publicly or commit it to version control.

Step 2: Configure in Masivo

Go to Settings → Integrations → Destinations in the Masivo dashboard
Click Add Destination and select TikTok
Enter your Pixel Code (format: C9XXXXXXXXXXXXXXXXXX)
Enter your Access Token
Enable the features you want to sync:
- Events: All standard conversion events
- Conversions: Track conversion events for ad optimization
- Purchases: Only fulfilled purchases
- Audiences: Calculate and Delete operations
- Customer tags: Sync customer tags for targeting

How it works

Once configured, Masivo automatically transforms and sends your data to TikTok Events API:

Real-time sync: Events are sent as they occur in Masivo
Smart transformation: Events are automatically transformed to TikTok’s format
Event mapping: Masivo events are mapped to TikTok standard events
Data validation: Configuration and data are validated before sending
Error handling: Failed syncs are logged for debugging

Automatic transformations

Masivo automatically handles several transformations to ensure compatibility:

Event names: Masivo events mapped to TikTok standard events
Field mapping: Common field names are mapped automatically
Contents array: Products/items are transformed to TikTok’s contents structure
Parameter flattening: Custom events flatten nested objects into flat key-value pairs
Timestamp conversion: Converts timestamps to TikTok’s Unix timestamp format

Event mapping

Masivo automatically maps common e-commerce events to TikTok standards:

Your event	TikTok event
`purchase`	`CompletePayment`
`PURCHASE`	`CompletePayment`
`add_to_cart`	`AddToCart`
`begin_checkout`	`InitiateCheckout`
`add_payment_info`	`AddPaymentInfo`
`view_item`	`ViewContent`
`search`	`Search`
`sign_up`	`CompleteRegistration`

Data structure

Event format for purchases

Masivo’s native purchase format (with order object) is automatically transformed for TikTok:

{
  "customer_id": "cust_123",
  "brand_id": null,
  "type": "PURCHASE",
  "order": {
    "purchase_id": "abc123",
    "value": 300,
    "discounted_value": 300,
    "products": [
      {
        "sku": "SKU-001",
        "name": "Running Shoes",
        "amount": 1,
        "value": 129.99
      }
    ],
    "payment_method": "CREDIT"
  },
  "fulfilled": true,
  "issued_at": "2024-10-17T10:30:00Z"
}

Automatic transformation:

order.products → contents array for TikTok
order.value → value
order.purchase_id → transaction_id
order.currency → currency (if present)
sku → content_id
name → content_name
amount → quantity

Contents array structure

For conversion events, each item in the contents array supports these TikTok fields:

{
  "content_id": "SKU-001", // Required: Product ID
  "content_name": "Running Shoes", // Required: Product name
  "content_type": "product", // Content type (product, product_group)
  "content_category": "Footwear", // Product category
  "brand": "Nike", // Brand name
  "price": 129.99, // Unit price
  "quantity": 1 // Quantity
}

At minimum, each content item must have either content_id or content_name. All other fields are optional but recommended for better ad optimization.

Field mapping

Masivo automatically maps common alternative field names to TikTok standards:

Your field	Maps to TikTok	Context
`id`	`content_id`	In items/contents
`sku`	`content_id`	In products
`item_id`	`content_id`	In items/contents
`name`	`content_name`	In items/contents
`item_name`	`content_name`	In items/contents
`unit_price`	`price`	In items/contents
`amount`	`quantity`	In products
`order.products`	`contents`	In PURCHASE events
`order.value`	`value`	In PURCHASE events
`order.purchase_id`	`transaction_id`	In PURCHASE events
`order_id`	`transaction_id`	In purchase events
`query`	`query`	In search events

Examples

Purchase event (Masivo native format)

{
  "customer_id": "cust_123",
  "type": "PURCHASE",
  "order": {
    "purchase_id": "order_789",
    "value": 300,
    "discounted_value": 275,
    "products": [
      {
        "sku": "SKU-001",
        "name": "Running Shoes",
        "amount": 1,
        "value": 129.99,
        "brand": "Nike"
      },
      {
        "sku": "SKU-002",
        "name": "Sports Socks",
        "amount": 2,
        "value": 15.99,
        "brand": "Adidas"
      }
    ],
    "payment_method": "CREDIT"
  },
  "fulfilled": true,
  "issued_at": "2024-10-17T10:30:00Z"
}

Purchase event (Alternative format)

{
  "type": "purchase",
  "customer_id": "cust_123",
  "currency": "USD",
  "value": 159.99,
  "transaction_id": "ORD-789",
  "items": [
    {
      "content_id": "SKU-001",
      "content_name": "Running Shoes",
      "brand": "Nike",
      "price": 129.99,
      "quantity": 1
    }
  ]
}

Add to cart event

{
  "type": "add_to_cart",
  "customer_id": "cust_123",
  "currency": "USD",
  "value": 49.99,
  "items": [
    {
      "content_id": "PROD-456",
      "content_name": "Wireless Headphones",
      "brand": "Sony",
      "content_category": "Electronics",
      "price": 49.99,
      "quantity": 1
    }
  ]
}

View content event

{
  "type": "view_item",
  "customer_id": "cust_123",
  "content_type": "product",
  "value": 79.99,
  "currency": "USD",
  "items": [
    {
      "content_id": "PROD-789",
      "content_name": "Smart Watch",
      "brand": "Apple",
      "price": 79.99
    }
  ]
}

Search event

{
  "type": "search",
  "customer_id": "cust_123",
  "query": "wireless headphones"
}

Button click event (Use exact TikTok name)

{
  "type": "ClickButton",
  "customer_id": "cust_123",
  "description": "Homepage CTA button clicked"
}

Form submission event (Use exact TikTok name)

{
  "type": "SubmitForm",
  "customer_id": "cust_123",
  "description": "Contact form submitted",
  "form_name": "Contact Us"
}

Truly custom event (not in TikTok catalog)

{
  "type": "free_trial_started",
  "customer_id": "cust_123",
  "plan_name": "Premium",
  "trial_days": 14
}

This becomes a custom event with parameters: custom_plan_name, custom_trial_days.

When to use each approach: - Use Auto-mapped events (purchase, add_to_cart) for convenience - Use Exact TikTok names (ClickButton, Subscribe) when you need those specific TikTok events - Use Custom events (free_trial_started) for tracking business-specific actions not in TikTok’s catalog

Audience synchronization

Audience calculation operations

When audiences are calculated in Masivo, they’re sent to TikTok Events API as custom events:

Event name: AudienceUpdated
Includes: audience_id, audience_name, customers_count, action
Customer IDs are included for reference

Audience DELETE operations

When audiences are deleted:

Event name: AudienceRemoved
Automatically includes all customers in the audience
Ensures proper cleanup in your TikTok tracking

Audience events use a special external_id of “audience_manager” and include all relevant customer information for proper tracking.

Validation

Before sending data to TikTok Events API, Masivo validates:

API credentials: Pixel Code and Access Token are configured correctly
Event configuration: The event type is enabled in your settings
Data completeness: Required fields are present for each event type
Purchase status: Only fulfilled purchases are sent (if configured)

Best practices

Always include customer_id: This becomes the external_id in TikTok
Use consistent content IDs: Ensures accurate product tracking and optimization
Include all content fields: Richer data enables better ad targeting
Add currency codes: Required for accurate revenue and ROAS tracking
Send timestamps: Use issued_at for accurate event timing
Include value for conversions: Essential for conversion optimization and bidding
Use content_type: Helps TikTok understand your catalog structure

TikTok Pixel vs Events API

Why use Events API?

Server-side tracking: No reliance on browser cookies or client-side tracking
Better data accuracy: Bypass ad blockers and browser restrictions
Complete data: Capture 100% of conversions, not just trackable ones
Privacy compliant: More control over data sharing and user privacy
Deduplication: TikTok automatically deduplicates with Pixel events

Use both TikTok Pixel (client-side) and Events API (server-side) together for the most comprehensive tracking. TikTok will automatically deduplicate events using the event_id parameter.

Conversion optimization

TikTok uses your conversion events to optimize ad delivery:

CompletePayment: Optimize for purchases and revenue
InitiateCheckout: Target users likely to start checkout
AddToCart: Reach users who add products to cart
ViewContent: Drive product page views
CompleteRegistration: Optimize for new user signups

For best results, send at least 50 conversion events per week per conversion event type. This gives TikTok enough data to optimize your campaigns.

Advanced features

User identification

TikTok matches events to users using:

external_id: Your customer ID (highest priority)
email: SHA256 hashed email address
phone: SHA256 hashed phone number
TikTok click ID: From ad clicks (ttclid parameter)

Masivo automatically sends the external_id (customer_id) for all events.

Value optimization

For value-based campaigns, always include:

value: Transaction or conversion value
currency: ISO 4217 currency code (USD, EUR, etc.)
contents: Product details for better optimization

Event deduplication

To prevent duplicate events when using both Pixel and Events API:

Use unique transaction_id for purchase events
TikTok automatically deduplicates based on event details
Masivo sends unique event timestamps to help with deduplication

Limitations

Contents array: Transformed from items/products array structure
Nested objects: Custom events flatten nested objects into custom_prefix_key format
Data types: Only primitives (string, number, boolean) are supported
Rate limits: Subject to TikTok Events API rate limits (typically 1000 events/second)
Event delay: Events can be sent up to 7 days after they occurred

Events older than 7 days will be rejected by TikTok. Ensure your integration is syncing regularly to avoid data loss.

Troubleshooting

Events not appearing in TikTok

Check that your Pixel Code starts with “C9”
Verify your Access Token is valid and not expired
Ensure the event type is enabled in Masivo settings
Check that customer_id is included in your events
Verify your Pixel is active in TikTok Ads Manager

Purchase events missing

Verify that “Purchases” is enabled in settings
Confirm purchases are marked as fulfilled
Check that transaction_id or order_id is unique for each purchase
Ensure contents array contains at least one item with content_id or content_name
Verify value and currency are included

Low conversion attribution

Ensure you’re sending customer_id for all events
Check that events are being sent within 7 days
Verify Pixel Code is correctly installed on your website
Consider implementing email/phone hashing for better matching

API errors

401 Unauthorized: Check your Access Token is valid
400 Bad Request: Verify your Pixel Code format (should start with C9)
403 Forbidden: Ensure your Access Token has proper permissions
429 Too Many Requests: You’re hitting rate limits, contact support

TikTok Events API has real-time processing. Events should appear in your Events Manager within a few minutes. Check the “Test Events” tool to verify your integration.

Testing your integration

To test your integration before going live:

Use the Test Events tool in TikTok Events Manager
Send test events through Masivo
Verify events appear in Events Manager within a few minutes
Check that event parameters are correct
Confirm conversion values are accurate

Use TikTok’s Test Events tool (Events Manager → Overview → Test Events) to see events in real-time and verify the data structure before sending production traffic.

Getting Access Token

Method 1: Through TikTok Ads Manager (Recommended)

Go to TikTok Ads Manager
Navigate to Tools → Events → Web Events
Select your Pixel
Click on Settings
Scroll to Events API section
Click Generate Access Token
Copy the token immediately (it won’t be shown again)

Method 2: Through TikTok for Business

Go to TikTok for Business
Create a developer account if you haven’t
Create an app in the Developer Portal
Request access to Events API
Generate long-term access token
Copy the token for use in Masivo

Access Tokens are sensitive credentials. Store them securely and never share them publicly. If compromised, regenerate immediately in TikTok Ads Manager.

Support and resources

Need help? Contact Masivo support with your Pixel Code (but never your Access Token) and we’ll help you troubleshoot your integration.

Get Started

Guides

Use cases

Integrations

​What you can sync

​Prerequisites

​Event types

​Standard conversion events (14 events)

​Custom events

​Configuration

​Step 1: Get your TikTok credentials

​Step 2: Configure in Masivo

​How it works

​Automatic transformations

​Event mapping

​Data structure

​Event format for purchases

​Contents array structure

​Field mapping

​Examples

​Purchase event (Masivo native format)

​Purchase event (Alternative format)

​Add to cart event

​View content event

​Search event

​Button click event (Use exact TikTok name)

​Form submission event (Use exact TikTok name)

​Truly custom event (not in TikTok catalog)

​Audience synchronization

​Audience calculation operations

​Audience DELETE operations

​Validation

​Best practices

​TikTok Pixel vs Events API

​Why use Events API?

​Conversion optimization

​Advanced features

​User identification

​Value optimization

​Event deduplication

​Limitations

​Troubleshooting

​Events not appearing in TikTok

​Purchase events missing

​Low conversion attribution

​API errors

​Testing your integration

​Getting Access Token

​Method 1: Through TikTok Ads Manager (Recommended)

​Method 2: Through TikTok for Business

​Support and resources

What you can sync

Prerequisites

Event types

Standard conversion events (14 events)

Custom events

Configuration

Step 1: Get your TikTok credentials

Step 2: Configure in Masivo

How it works

Automatic transformations

Event mapping

Data structure

Event format for purchases

Contents array structure

Field mapping

Examples

Purchase event (Masivo native format)

Purchase event (Alternative format)

Add to cart event

View content event

Search event

Button click event (Use exact TikTok name)

Form submission event (Use exact TikTok name)

Truly custom event (not in TikTok catalog)

Audience synchronization

Audience calculation operations

Audience DELETE operations

Validation

Best practices

TikTok Pixel vs Events API

Why use Events API?

Conversion optimization

Advanced features

User identification

Value optimization

Event deduplication

Limitations

Troubleshooting

Events not appearing in TikTok

Purchase events missing

Low conversion attribution

API errors

Testing your integration

Getting Access Token

Method 1: Through TikTok Ads Manager (Recommended)

Method 2: Through TikTok for Business

Support and resources