> ## Documentation Index
> Fetch the complete documentation index at: https://docs.masivo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TikTok Events API integration

> Sync Masivo customers, events, and conversions to TikTok for ad optimization

## 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

<Info>
  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**.
</Info>

## 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:

```json theme={null}
{
  "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

1. Log in to [TikTok Ads Manager](https://ads.tiktok.com)
2. Navigate to **Assets → Events → Web Events**
3. Select your Pixel or create a new one
4. Copy your **Pixel Code** (starts with `C9`)
5. Go to **Settings → Generate Access Token**
6. Copy the generated **Access Token**

<Warning>
  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.
</Warning>

### Step 2: Configure in Masivo

1. Go to **Settings → Integrations → Destinations** in the Masivo dashboard
2. Click **Add Destination** and select **TikTok**
3. Enter your **Pixel Code** (format: `C9XXXXXXXXXXXXXXXXXX`)
4. Enter your **Access Token**
5. Enable the features you want to sync:
   * **Events**: All standard conversion events
   * **Purchases**: Only fulfilled purchases
   * **Audiences**: Calculate and Delete operations

## How it works

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

1. **Real-time sync**: Events are sent as they occur in Masivo
2. **Smart transformation**: Events are automatically transformed to TikTok's format
3. **Event mapping**: Masivo events are mapped to TikTok standard events
4. **Data validation**: Configuration and data are validated before sending
5. **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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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
}
```

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

## Field mapping

Masivo automatically maps common alternative field names to TikTok standards:

| Your field          | Maps to TikTok   | Context            |
| ------------------- | ---------------- | ------------------ |
| `customer_id`       | `external_id`    | Event level        |
| `id`                | `content_id`     | In items/contents  |
| `sku`               | `content_id`     | In products        |
| `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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "type": "search",
  "customer_id": "cust_123",
  "query": "wireless headphones"
}
```

### Button click event (Use exact TikTok name)

```json theme={null}
{
  "type": "ClickButton",
  "customer_id": "cust_123",
  "description": "Homepage CTA button clicked"
}
```

### Form submission event (Use exact TikTok name)

```json theme={null}
{
  "type": "SubmitForm",
  "customer_id": "cust_123",
  "description": "Contact form submitted",
  "form_name": "Contact Us"
}
```

### Truly custom event (not in TikTok catalog)

```json theme={null}
{
  "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`.

<Info>
  **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
</Info>

## 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

<Note>
  Audience events use a special `external_id` of "audience\_manager" and include
  all relevant customer information for proper tracking.
</Note>

## 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

1. **Always include customer\_id**: Required for user identification (automatically mapped to TikTok's `external_id`)
2. **Use consistent content IDs**: Ensures accurate product tracking and optimization
3. **Include all content fields**: Richer data enables better ad targeting
4. **Add currency codes**: Required for accurate revenue and ROAS tracking
5. **Send timestamps**: Use `issued_at` for accurate event timing
6. **Include value for conversions**: Essential for conversion optimization and bidding
7. **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

<Tip>
  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.
</Tip>

## 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

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

## Advanced features

### User identification

TikTok matches events to users using:

1. **external\_id**: Your customer ID (highest priority)
2. **email**: SHA256 hashed email address
3. **phone**: SHA256 hashed phone number
4. **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:

1. Use unique `transaction_id` for purchase events
2. TikTok automatically deduplicates based on event details
3. 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

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

## 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

<Info>
  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.
</Info>

## Testing your integration

To test your integration before going live:

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

<Tip>
  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.
</Tip>

## Getting Access Token

### Method 1: Through TikTok Ads Manager (Recommended)

1. Go to [TikTok Ads Manager](https://ads.tiktok.com)
2. Navigate to **Tools → Events → Web Events**
3. Select your Pixel
4. Click on **Settings**
5. Scroll to **Events API** section
6. Click **Generate Access Token**
7. Copy the token immediately (it won't be shown again)

### Method 2: Through TikTok for Business

1. Go to [TikTok for Business](https://business-api.tiktok.com/)
2. Create a developer account if you haven't
3. Create an app in the Developer Portal
4. Request access to Events API
5. Generate long-term access token
6. Copy the token for use in Masivo

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

## Support and resources

* [TikTok Events API Documentation](https://business-api.tiktok.com/portal/docs?id=1741601162187777)
* [TikTok Ads Manager](https://ads.tiktok.com)
* [TikTok Events Manager](https://ads.tiktok.com/i18n/events_manager)
* [TikTok Conversion Events](https://ads.tiktok.com/help/article?aid=10028)

<Note>
  Need help? Contact Masivo support with your Pixel Code (but never your Access
  Token) and we'll help you troubleshoot your integration.
</Note>