> Part of the walkerOS documentation. Project overview and full index: <https://www.walkeros.io/llms.txt>

# Pinterest Conversions API

<!-- -->

[Server](#)[ ](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/pinterest)

<!-- -->

[Source code](https://github.com/elbwalker/walkerOS/tree/main/packages/server/destinations/pinterest)[ ](https://www.npmjs.com/package/@walkeros/server-destination-pinterest)

<!-- -->

[Package](https://www.npmjs.com/package/@walkeros/server-destination-pinterest)

Server-side event delivery to Pinterest's Conversions API for enhanced conversion tracking, bypassing browser limitations for improved data quality and privacy compliance.

<!-- -->

Where this fits

Pinterest Conversions API is a **server destination** in the walkerOS flow:

Sends events server-side to Pinterest's Conversions API via raw HTTP (\`POST https\://api.pinterest.com/v5/ad\_accounts/<!-- -->{adAccountId}<!-- -->/events\`), hashing 12 user\_data fields with SHA-256 before transmission. Supports deduplication with the web Pinterest Tag via \`event\_id\` + \`event\_name\`.

## Installation[​](#installation "Direct link to Installation")

```
npm install @walkeros/server-destination-pinterest
```

* Integrated
* Bundled

```
import { startFlow } from '@walkeros/collector';
import { destinationPinterest } from '@walkeros/server-destination-pinterest';

await startFlow({
  destinations: {
    pinterest: {
      code: destinationPinterest,
      config: {
        settings: {
          accessToken: 'YOUR_ACCESS_TOKEN',
          adAccountId: 'YOUR_AD_ACCOUNT_ID',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```
"destinations": {
  "pinterest": {
    "package": "@walkeros/server-destination-pinterest",
    "import": "destinationPinterest",
    "config": {
      "settings": {
        "accessToken": "YOUR_ACCESS_TOKEN",
        "adAccountId": "YOUR_AD_ACCOUNT_ID"
      }
    }
  }
}
```

[See bundled mode setup](https://www.walkeros.io/docs/getting-started/modes/bundled.md) | [CLI reference](https://www.walkeros.io/docs/apps/cli.md)

## Configuration[​](#configuration "Direct link to Configuration")

This <!-- -->destination<!-- --> uses the standard <!-- -->destination<!-- --> config wrapper (consent, data, env, id, ...). For the shared fields see [destination<!-- --> configuration](https://www.walkeros.io/docs/destinations.md#configuration). Package-specific fields live under `config.settings` and are listed below.

## Settings[​](#settings "Direct link to Settings")

| Property        | Type                               | Description                                                 | More |
| --------------- | ---------------------------------- | ----------------------------------------------------------- | ---- |
| `accessToken*`  | `string`                           | Pinterest conversion access token for Bearer authentication |      |
| `adAccountId*`  | `string`                           | Pinterest ad account ID from Ads Manager                    |      |
| `action_source` | `'app_android' \| 'app_ios' \| 'w` | Source of the event (web, app\_android, app\_ios, offline)  |      |
| `doNotHash`     | `Array<string>`                    | Array of user\_data fields that should not be hashed        |      |
| `test`          | `boolean`                          | Enable test mode by appending ?test=true to the API URL     |      |
| `url`           | `string`                           | Custom URL for Pinterest Conversions API endpoint           |      |
| `user_data`     | `Record<string, string>`           | Mapping configuration for user data fields                  |      |
| `partner_name`  | `string`                           | Third-party partner name for attribution                    |      |

\* Required fields

## Mapping[​](#mapping "Direct link to Mapping")

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

## Examples

### Add to cart

A product add is sent to Pinterest as an add\_to\_cart conversion with the added item details.

Event

```
{
  "name": "product add",
  "data": {
    "id": "SKU-B2",
    "name": "Cool Cap",
    "price": "42.00",
    "quantity": 1
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-456"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "a1b2c3d4e5f60002",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000901,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://shop.example.com/products"
  }
}
```

Mapping

```
{
  "name": "add_to_cart",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "value": "data.price",
          "currency": {
            "value": "EUR"
          },
          "contents": {
            "set": [
              {
                "map": {
                  "id": "data.id",
                  "item_name": "data.name",
                  "item_price": "data.price",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

Out

```
sendServer("https://api.pinterest.com/v5/ad_accounts/123456789/events", "{\"data\":[{\"event_name\":\"add_to_cart\",\"event_id\":\"a1b2c3d4e5f60002\",\"event_time\":1700001,\"action_source\":\"web\",\"user_data\":{},\"custom_data\":{\"value\":\"42.00\",\"currency\":\"EUR\",\"contents\":[{\"id\":\"SKU-B2\",\"item_name\":\"Cool Cap\",\"item_price\":\"42.00\",\"quantity\":1}]},\"event_source_url\":\"https://shop.example.com/products\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})
```

### Checkout

A completed order is sent to the Pinterest Conversions API as a checkout event with value, currency, and contents.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "ORD-300",
    "total": 249.99,
    "currency": "EUR"
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-123",
    "device": "device-456"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "SKU-A1",
        "name": "Everyday Ruck Snack",
        "price": "129.99",
        "quantity": 2
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "a1b2c3d4e5f60001",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000900,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://shop.example.com"
  }
}
```

Mapping

```
{
  "name": "checkout",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "value": "data.total",
          "currency": {
            "key": "data.currency",
            "value": "EUR"
          },
          "order_id": "data.id",
          "num_items": {
            "fn": {
              "$code": "e=>e.nested.filter(e=>\"product\"===e.entity).length"
            }
          },
          "contents": {
            "loop": [
              "nested",
              {
                "condition": {
                  "$code": "e=>b(e)&&\"product\"===e.entity"
                },
                "map": {
                  "id": "data.id",
                  "item_name": "data.name",
                  "item_price": "data.price",
                  "quantity": {
                    "key": "data.quantity",
                    "value": 1
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}
```

Out

```
sendServer("https://api.pinterest.com/v5/ad_accounts/123456789/events", "{\"data\":[{\"event_name\":\"checkout\",\"event_id\":\"a1b2c3d4e5f60001\",\"event_time\":1700001,\"action_source\":\"web\",\"user_data\":{},\"custom_data\":{\"value\":249.99,\"currency\":\"EUR\",\"order_id\":\"ORD-300\",\"num_items\":1,\"contents\":[{\"id\":\"SKU-A1\",\"item_name\":\"Everyday Ruck Snack\",\"item_price\":\"129.99\",\"quantity\":2}]},\"event_source_url\":\"https://shop.example.com\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})
```

### Page visit

A page view is sent to Pinterest as a page\_visit conversion with the source URL.

Event

```
{
  "name": "page view",
  "data": {
    "domain": "www.example.com",
    "title": "walkerOS documentation",
    "referrer": "https://www.walkeros.io/",
    "search": "?foo=bar",
    "hash": "#hash",
    "id": "/docs/"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "pagegroup": "docs"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-789"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "a1b2c3d4e5f60003",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000902,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/docs/"
  }
}
```

Mapping

```
{
  "name": "page_visit"
}
```

Out

```
sendServer("https://api.pinterest.com/v5/ad_accounts/123456789/events", "{\"data\":[{\"event_name\":\"page_visit\",\"event_id\":\"a1b2c3d4e5f60003\",\"event_time\":1700001,\"action_source\":\"web\",\"user_data\":{},\"event_source_url\":\"https://www.example.com/docs/\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})
```

### Search

A site search event is forwarded to Pinterest as a search conversion with the query in custom data.

Event

```
{
  "name": "entity action",
  "data": {
    "query": "walkerOS destinations"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "user-101"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "a1b2c3d4e5f60004",
  "trigger": "test",
  "entity": "entity",
  "action": "action",
  "timestamp": 1700000903,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/search"
  }
}
```

Mapping

```
{
  "name": "search",
  "data": {
    "map": {
      "custom_data": {
        "map": {
          "search_string": "data.query"
        }
      }
    }
  }
}
```

Out

```
sendServer("https://api.pinterest.com/v5/ad_accounts/123456789/events", "{\"data\":[{\"event_name\":\"search\",\"event_id\":\"a1b2c3d4e5f60004\",\"event_time\":1700001,\"action_source\":\"web\",\"user_data\":{},\"custom_data\":{\"search_string\":\"walkerOS destinations\"},\"event_source_url\":\"https://www.example.com/search\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})
```

### Signup

A user signup is sent to Pinterest as a signup conversion with the hashed email and external id.

Event

```
{
  "name": "entity action",
  "data": {
    "method": "email"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "new-user-1",
    "email": "new@example.com"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "a1b2c3d4e5f60005",
  "trigger": "test",
  "entity": "entity",
  "action": "action",
  "timestamp": 1700000904,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "browser",
    "platform": "web",
    "url": "https://www.example.com/register"
  }
}
```

Mapping

```
{
  "name": "signup",
  "data": {
    "map": {
      "user_data": {
        "map": {
          "em": {
            "set": [
              "user.email"
            ]
          },
          "external_id": {
            "set": [
              "user.id"
            ]
          }
        }
      }
    }
  }
}
```

Out

```
sendServer("https://api.pinterest.com/v5/ad_accounts/123456789/events", "{\"data\":[{\"event_name\":\"signup\",\"event_id\":\"a1b2c3d4e5f60005\",\"event_time\":1700001,\"action_source\":\"web\",\"user_data\":{\"em\":[\"f0030501023327437b06e5c6f87df7871b8e704ae608d1d0b7b24fdd2a06c716\"],\"external_id\":[\"b45cf5f6ebc2c6974ea3bd9fab19f8cc3a7cf63054727a9fcd22f1fda97d6dde\"]},\"event_source_url\":\"https://www.example.com/register\"}]}", {
  "headers": {
    "Authorization": "Bearer s3cr3t"
  }
})
```