> 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/pinterest/pinterest-conversions-api.md).

# Pinterest Conversions API

The **Pinterest Conversions API** destination sends event data directly from Chord to Pinterest's servers, bypassing the browser entirely. Unlike the [Pinterest Tag](/activate/event-streaming/destinations/advertising/pinterest/pinterest-tag.md), server events aren't affected by ad blockers or browser tracking restrictions, so they give a more reliable signal for campaign measurement, audience building and automated bidding optimization.

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

## Getting started

You need:

* Your Pinterest ad account ID, found in the Pinterest Ads dashboard.
* A conversion token, generated in Pinterest Ads under **Conversions**. See [Pinterest's documentation](https://developers.pinterest.com/docs/conversions/conversions/) for how to create one.

## Settings

* **Destination Name** (required): a name to tell this destination apart.
* **App Name** (required): the name of the site the events come from, for example `my-storefront`. Chord sends it as `app_name`.
* **Ad Account ID** (required): your Pinterest ad account ID.
* **Conversion Token** (required): your Pinterest conversion token.
* **Test Mode** (optional): shows every event in Pinterest's debug tool. Off by default. Turn it off to send live events.
* **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 **Pinterest 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 event                                                                             | Pinterest event                                                                               | Notes |
| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ----- |
| `page`                                                                                  | `page_visit`                                                                                  |       |
| [`Order Completed`](/collect-data/tracking-plan/order-completed.md)                     | `checkout`                                                                                    |       |
| [`Checkout Started`](/collect-data/tracking-plan/checkout-started.md)                   | `initiate_checkout`                                                                           |       |
| [`Payment Info Entered`](/collect-data/tracking-plan/payment-info-entered.md)           | `add_payment_info`                                                                            |       |
| [`Product Added`](/collect-data/tracking-plan/product-added.md)                         | `add_to_cart`                                                                                 |       |
| [`Product Added to Wishlist`](/collect-data/tracking-plan/product-added-to-wishlist.md) | `add_to_wishlist`                                                                             |       |
| [`Product Viewed`](/collect-data/tracking-plan/product-viewed.md)                       | `view_content`                                                                                |       |
| [`Product List Viewed`](/collect-data/tracking-plan/product-list-viewed.md)             | `view_category`                                                                               |       |
| [`Products Searched`](/collect-data/tracking-plan/products-searched.md)                 | `search`                                                                                      |       |
| `Products List Filtered`                                                                | `search`                                                                                      |       |
| [`Signed Up`](/collect-data/tracking-plan/signed-up.md)                                 | `signup`                                                                                      |       |
| [`Email Captured`](/collect-data/tracking-plan/email-captured.md)                       | `lead`                                                                                        |       |
| *(other track events)*                                                                  | Custom event named after the Chord event (e.g. `Newsletter Signed Up` → `NewsletterSignedUp`) |       |

Mapped events use Pinterest's own lowercase event names, which differ from the Pinterest Tag's (`AddToCart` in the tag is `add_to_cart` here).

## Common event fields

Page and track events are forwarded. Identify and screen events are ignored.

| Chord source (priority order)                                         | Pinterest field                               | Notes                                                                                     |
| --------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
| See the event mapping above                                           | `event_name`                                  |                                                                                           |
| `messageId`                                                           | `event_id`                                    | Used for deduplication with the Pinterest Tag. Chord makes up an ID if the event has none |
| `timestamp`                                                           | `event_time`                                  | Unix seconds. Uses the current time if the event has no timestamp                         |
| *(hardcoded)* `"web"`                                                 | `action_source`                               |                                                                                           |
| *(hardcoded)* `"chord"`                                               | `partner_name`                                |                                                                                           |
| `context.page.url`                                                    | `event_source_url`                            |                                                                                           |
| **App Name**                                                          | `app_name`                                    |                                                                                           |
| `context.opt_out`                                                     | `opt_out`                                     |                                                                                           |
| `context.app.id`, `context.app.version`                               | `app_id`, `app_version`                       |                                                                                           |
| `context.device.brand`, `context.device.model`, `context.device.type` | `device_brand`, `device_model`, `device_type` |                                                                                           |
| `context.network.carrier`                                             | `device_carrier`                              |                                                                                           |
| `context.os.version`                                                  | `os_version`                                  |                                                                                           |
| The language part of `context.locale`                                 | `language`                                    | For example `en` from `en-US`                                                             |
| `context.network.wifi`                                                | `wifi`                                        | Omitted if not present                                                                    |

## User data (all events)

Personally identifiable information (PII) is normalized and SHA-256 hashed before it is sent; a value that is already a SHA-256 hex digest is passed through unchanged. Pinterest matches on the hashed values. IP address and user agent are sent unhashed. Fields that cannot be resolved are omitted.

| Chord source (priority order)                                             | Pinterest field      | Notes                                                    |
| ------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------- |
| `properties.email` > `context.traits.email` > `traits.email`              | `em` (email)         | Hashed array; lowercased and trimmed                     |
| `properties.phone` > `context.traits.phone` > `traits.phone`              | `ph` (phone)         | Hashed array; digits only, leading zeros removed         |
| `properties.first_name` > `context.traits.firstName`                      | `fn` (first name)    | Hashed array; lowercased                                 |
| `properties.last_name` > `context.traits.lastName`                        | `ln` (last name)     | Hashed array; lowercased                                 |
| `context.traits.gender`                                                   | `ge` (gender)        | Hashed array; first letter, lowercased                   |
| `context.traits.birthday`                                                 | `db` (date of birth) | Hashed array; `YYYYMMDD`                                 |
| `city` from the address                                                   | `ct` (city)          | Hashed array; lowercased, spaces and punctuation removed |
| `state` from the address                                                  | `st` (state)         | Hashed array; lowercased                                 |
| `postalCode` from the address                                             | `zp` (zip)           | Hashed array; digits only. Chord does not read `zipcode` |
| `country` from the address                                                | `country`            | Hashed array; first 2 letters, lowercased                |
| `userId` > `anonymousId`                                                  | `external_id`        | Hashed array; omitted if neither is present              |
| `context.device.advertisingId` / `idfa` / `adid`                          | `hashed_maids`       | Hashed array                                             |
| The IP address the server received > `context.ip`                         | `client_ip_address`  | Not hashed                                               |
| `context.userAgent` > `context.user_agent`                                | `client_user_agent`  | Not hashed. Defaults to `"Mozilla/5.0"` if not present   |
| `epik` query parameter from `context.page.url` > `context.clientIds.epik` | `click_id`           | Pinterest click ID                                       |
| `properties.partner_id` > `context.campaign.name`                         | `partner_id`         |                                                          |

The address is the first of `context.traits.address`, `traits.address` or `properties.address` that exists. Chord does not mix fields from different addresses.

## Custom data (track events)

Track events include a `custom_data` block with the following structured schema fields. Additionally, any `properties.*` destination mappings you configure in Chord that target other fields are forwarded as custom properties alongside the structured fields.

| Chord source (priority order)                                                                                                   | Pinterest field | Notes                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `properties.value` > `properties.price` > `properties.revenue` > sum of `price × quantity` across products                      | `value`         | String; `null` if none is present                                                                                                     |
| `properties.currency` > `properties.meta.i18n.currency`                                                                         | `currency`      | Defaults to `"USD"`                                                                                                                   |
| `properties.order_id` > `properties.cart_id`                                                                                    | `order_id`      |                                                                                                                                       |
| Product IDs from the top-level `properties.product_id` or `properties.sku` when present, otherwise from `properties.products[]` | `content_ids`   | Each product ID is `product_id` > `id` > `sku` > `variant`. With no products, falls back to `properties.title` > `context.page.title` |
| Array of `{ id, item_price, quantity, item_name, item_category, item_brand }` per product                                       | `contents`      | Omitted if no products. `quantity` defaults to `1`                                                                                    |
| `properties.quantity` > sum of quantities across `properties.products[]`                                                        | `num_items`     |                                                                                                                                       |
| `properties.query` > `properties.search_term`                                                                                   | `search_string` |                                                                                                                                       |
| `properties.opt_out_type` > `context.opt_out_type`                                                                              | `opt_out_type`  |                                                                                                                                       |

## Custom events

Any other track event is sent as a Pinterest custom event under its own name, so each one appears separately in Pinterest rather than grouped under the deprecated "Custom event (Legacy)" type. Pinterest custom event names cannot contain spaces and are limited to 100 characters, so spaces are removed from the Chord event name before sending (`Coupon Applied` → `CouponApplied`, `Product Added to Bundle` → `ProductAddedtoBundle`) and names longer than 100 characters are truncated. Any other characters are sent as they are.

**Map each custom event in Pinterest.** Pinterest requires every custom event to be mapped to a standard event (for example Sign Up, Lead or Checkout), either in Pinterest or through its advertiser-defined events API. An unmapped custom event is received but treated as untracked, and cannot be used for reporting or campaign optimization. Pinterest allows up to 15 custom event types per ad account, so map only the events you plan to report on or optimize for. Enter the name exactly as it is sent (with spaces removed); Pinterest matches names case-insensitively.

## Custom property forwarding

Configure destination mappings in Chord with `properties.*` destination paths to forward additional event properties into `custom_data`. 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, `custom_data.loyalty_tier` will appear in the payload sent to Pinterest.

**What is excluded:**

* Fields Chord already computes: `product_id`, `sku`, `products`, `price`, `value`, `revenue`, `quantity`, `currency`, `order_id`, `cart_id`, `query`, `search_term`, `opt_out_type`, `title` and `partner_id`.
* User data fields (`email`, `phone`, `first_name`, `last_name` and `address`). Chord sends these in the user data block, hashed.

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

## Testing and validation

After connecting the destination:

1. Trigger events from your storefront or use the **Live Events** tab in Chord to confirm events are flowing.
2. In Pinterest Ads Manager, navigate to **Ads > Conversions** and open your conversion tag to verify events are received.
3. Confirm revenue values and order counts align with your expectations.
4. If you are running both the Conversions API and the Pinterest Tag, the `event_id` values must match across both to prevent duplicate counting. Chord handles this by using `messageId` as the `event_id` for both destinations.


---

# 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/pinterest/pinterest-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.