> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/advertising/tiktok/tiktok-conversions-api.md).

# TikTok Conversions API

The **TikTok Conversions API** destination sends event data directly from Chord to TikTok's servers, bypassing the browser entirely. Unlike the [TikTok Pixel](/activate/event-streaming/destinations/advertising/tiktok/tiktok-pixel.md), server events aren't affected by ad blockers or browser tracking restrictions, so they give a more reliable signal for attribution and optimization.

Use this destination alongside the [TikTok Pixel](/activate/event-streaming/destinations/advertising/tiktok/tiktok-pixel.md) for maximum data coverage. TikTok deduplicates events using the `event_id` field. See [TikTok](/activate/event-streaming/destinations/advertising/tiktok.md) for how the two fit together.

## Getting started

You need:

* An access token, generated in TikTok Ads Manager or through the TikTok API. See TikTok's [Events API documentation](https://ads.tiktok.com/marketing_api/docs?id=1701890979375106).
* Your TikTok Pixel ID, found in TikTok Ads Manager under **Assets > Events > Web Events**.

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **Access Token** (required): your TikTok access token.
* **Pixel Code** (required): your TikTok Pixel ID.
* **Test Event Code** (optional): the test event code from TikTok Events Manager. When set, events are tagged as test events and show up in TikTok's test events view.
* **Product Content ID Field** (required): which product field to send as the content ID: `sku`, `variant_id`, `product_id` or `id`. Defaults to `sku`. The value must match your product catalog.
* **Dedup Source Property** (optional): a property path, for example `properties.order_id`, that Chord uses as the event ID for deduplication with the TikTok Pixel. If it is empty, or the event has no value there, Chord uses the message ID. Set the same value on the TikTok Pixel destination. See [TikTok](/activate/event-streaming/destinations/advertising/tiktok.md).
* **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md).

## Connect

Add **TikTok Conversions** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps.

## Event mapping

Chord sends page and track events. Identify events are ignored.

| Chord event                                                                             | TikTok event                                                     | Notes |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ----- |
| `page`                                                                                  | `PageView`                                                       |       |
| [`Order Completed`](/collect-data/tracking-plan/order-completed.md)                     | `CompletePayment`                                                |       |
| [`Checkout Started`](/collect-data/tracking-plan/checkout-started.md)                   | `InitiateCheckout`                                               |       |
| [`Product Added`](/collect-data/tracking-plan/product-added.md)                         | `AddToCart`                                                      |       |
| [`Product Viewed`](/collect-data/tracking-plan/product-viewed.md)                       | `ViewContent`                                                    |       |
| [`Products Searched`](/collect-data/tracking-plan/products-searched.md)                 | `Search`                                                         |       |
| [`Payment Info Entered`](/collect-data/tracking-plan/payment-info-entered.md)           | `AddPaymentInfo`                                                 |       |
| [`Product Added to Wishlist`](/collect-data/tracking-plan/product-added-to-wishlist.md) | `AddToWishlist`                                                  |       |
| [`Product Clicked`](/collect-data/tracking-plan/product-clicked.md)                     | `ClickButton`                                                    |       |
| [`Signed Up`](/collect-data/tracking-plan/signed-up.md)                                 | `CompleteRegistration`                                           |       |
| [`Email Captured`](/collect-data/tracking-plan/email-captured.md)                       | `Lead`                                                           |       |
| [`Subscription Created`](/collect-data/tracking-plan/subscription-created.md)           | `Subscribe`                                                      |       |
| `Form Submitted`                                                                        | `SubmitForm`                                                     |       |
| `Callback Started`                                                                      | `Contact`                                                        |       |
| `Download Link Clicked`                                                                 | `Download`                                                       |       |
| *(any other track event)*                                                               | The Chord event name, as is. See [Custom events](#custom-events) |       |

## User data (all events)

Chord hashes each value with SHA-256 before sending, except where noted. A value that is already a SHA-256 digest is sent as is.

| Chord source (priority order)                                                                   | TikTok field  | Notes                                                                                                                          |
| ----------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `userId` > `anonymousId`                                                                        | `external_id` | Lowercased, SHA-256 hashed                                                                                                     |
| `properties.email` > `context.traits.email`                                                     | `email`       | Lowercased, SHA-256 hashed                                                                                                     |
| `properties.phone` > `context.traits.phone`                                                     | `phone`       | E.164 format, SHA-256 hashed. A value with fewer than 7 digits, one repeated digit, or a placeholder such as `n/a` is not sent |
| `properties.first_name` > `context.traits.first_name` > the event's `first_name`                | `first_name`  | Lowercased, whitespace removed, SHA-256 hashed                                                                                 |
| `properties.last_name` > `context.traits.last_name` > the event's `last_name`                   | `last_name`   | Lowercased, whitespace removed, SHA-256 hashed                                                                                 |
| `city` from the address                                                                         | `city`        | Lowercased, non-alphanumeric characters removed. Not hashed                                                                    |
| `state` from the address                                                                        | `state`       | Lowercased, non-alphanumeric characters removed. Not hashed                                                                    |
| `country` from the address                                                                      | `country`     | Lowercased, non-alphanumeric characters removed. Not hashed                                                                    |
| `postal_code` > `zip_code` from the address                                                     | `zip_code`    | Lowercased, whitespace removed, SHA-256 hashed                                                                                 |
| `context.ip`                                                                                    | `ip`          | Not hashed                                                                                                                     |
| `context.userAgent`                                                                             | `user_agent`  | Not hashed                                                                                                                     |
| `context.locale`                                                                                | `locale`      | Not hashed                                                                                                                     |
| `properties.ttclid` > the `ttclid` query parameter of the page URL > `context.clientIds.ttclid` | `ttclid`      | TikTok click ID. Not hashed                                                                                                    |
| `properties.ttp` > `context.clientIds.ttp`                                                      | `ttp`         | TikTok cookie. Not hashed                                                                                                      |
| `properties.lead_id`                                                                            | `lead_id`     | Omitted if not present. Not hashed                                                                                             |

The address is the first of `properties.address`, `context.traits.address` or the event's `address` that exists. Chord does not mix fields from different addresses. Chord reads only the `postal_code` and `zip_code` fields for the zip code, not `zipcode`.

## Page data (all events)

| Chord source (priority order)                         | TikTok field | Notes |
| ----------------------------------------------------- | ------------ | ----- |
| The event's `page.url` > `context.page.url`           | `url`        |       |
| The event's `page.referrer` > `context.page.referrer` | `referrer`   |       |

## Event data (all events)

| Chord source (priority order)                   | TikTok field       | Notes                                                                    |
| ----------------------------------------------- | ------------------ | ------------------------------------------------------------------------ |
| Mapped event name                               | `event`            | See the event mapping above                                              |
| `timestamp`                                     | `event_time`       | Unix seconds. Uses the current time if the event has no timestamp        |
| The property named in **Dedup Source Property** | `event_id`         | Falls back to `messageId`. Used for deduplication with the browser pixel |
| The event's top-level `limited_data_use` field  | `limited_data_use` | Defaults to `false`                                                      |

## Order properties (all track events)

| Chord source (priority order)                                                                                    | TikTok field   | Notes                                                                                                                             |
| ---------------------------------------------------------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `properties.currency` > `properties.meta.i18n.currency`                                                          | `currency`     | Omitted if neither is present                                                                                                     |
| `properties.value` > `properties.revenue` > `properties.price` > the sum of `price × quantity` across `contents` | `value`        |                                                                                                                                   |
| `properties.order_id`                                                                                            | `order_id`     | Omitted if not present                                                                                                            |
| `properties.shop_id`                                                                                             | `shop_id`      | Omitted if not present                                                                                                            |
| `properties.content_type`                                                                                        | `content_type` | `"product_group"` if that is the value, otherwise `"product"`. If the property is empty and the event has `contents`, `"product"` |
| `properties.description`                                                                                         | `description`  |                                                                                                                                   |
| `properties.query` > `properties.search_term`                                                                    | `query`        | Products Searched only                                                                                                            |
| `properties.form_name` > `properties.name`                                                                       | `form_name`    | Form Submitted only                                                                                                               |

## Products

Each product becomes one item in `contents`. Which products Chord reads depends on the event:

* **Order Completed, Checkout Started and Payment Info Entered** read every item in `properties.products[]`.
* **All other events** read the product from the top-level `properties`, and use the first item of `properties.products[]` for any field the top level lacks.

| Chord source (priority order)                                              | TikTok field       | Notes |
| -------------------------------------------------------------------------- | ------------------ | ----- |
| The field you chose in **Product Content ID Field**, read from the product | `content_id`       |       |
| Product `name`                                                             | `content_name`     |       |
| Product `category`                                                         | `content_category` |       |
| Product `price`                                                            | `price`            |       |
| Product `quantity`, which defaults to `1`                                  | `quantity`         |       |
| Product `brand`                                                            | `brand`            |       |

If **Product Content ID Field** is not set, which only happens on destinations created before the field existed, `content_id` is the product's `sku` > `product_id` > `id`. If a product has no value in the chosen field, `content_id` is left out.

## Custom events

Any track event that is not in the event mapping is sent to TikTok under its Chord event name, as is. TikTok accepts any event name for reporting and audience segmentation, but only TikTok standard event names support campaign bid optimization.

If the TikTok event name you want does not match your Chord event name, use a property mapping in Chord to rename the event before it reaches this destination.

## Testing and validation

After connecting the destination:

1. Set a **Test Event Code** in the destination configuration.
2. Trigger events from your storefront or use the **Live Events** tab in Chord.
3. In TikTok Ads Manager, navigate to **Assets > Events > Web Events** and open the **Test Events** tab to verify events are received.
4. Remove the **Test Event Code** before going live to avoid events being excluded from campaigns.

## Custom property forwarding

Configure destination mappings in Chord with `properties.*` destination paths to forward additional event properties into the TikTok event's `properties` object (the same object that holds `currency`, `value`, `contents`, etc.). Only explicitly-configured non-schema fields are forwarded — nothing flows through automatically.

**How to configure:**

1. In Chord, open the destination's connection and find **Property Mappings**. See [Property mappings](/activate/event-streaming/property-mappings.md#add-a-mapping) for the steps.
2. Add a mapping with source path `properties.loyalty_tier` and destination path `properties.loyalty_tier`.
3. On the next event, `loyalty_tier` will appear in the properties payload sent to TikTok.

**What is excluded:**

* Fields Chord already computes: `currency`, `value`, `revenue`, `price`, `order_id`, `shop_id`, `form_name`, `name`, `query`, `search_term`, `content_type`, `description` and `products`.
* User data fields (`email`, `phone`, `first_name`, `last_name`, `address`, `ttclid`, `ttp` and `lead_id`). Chord sends these in the user data block, hashed where noted above.

A mapping to a field that Chord computes is ignored. The computed value is always the one sent.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.chord.co/activate/event-streaming/destinations/advertising/tiktok/tiktok-conversions-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.