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

# Pinterest Tag

<!-- -->

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

<!-- -->

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

<!-- -->

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

The [Pinterest Tag](https://help.pinterest.com/en/business/article/install-the-pinterest-tag) forwards browser conversions to Pinterest Ads Manager for ad optimization, retargeting, and audience building. This destination wraps the standard Pinterest Tag snippet (loaded from `s.pinimg.com/ct/core.js`); there is no npm SDK for the browser tag. Mapped events become `window.pintrk('track', eventName, { ..., event_id })` calls, with optional `pintrk('set', ...)` for enhanced matching.

<!-- -->

Where this fits

Pinterest Tag is a **web destination** in the walkerOS flow:

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

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

* Integrated
* Bundled

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

await startFlow({
  consent: { marketing: false },
  destinations: {
    pinterest: {
      code: destinationPinterest,
      config: {
        consent: { marketing: true },
        loadScript: true,
        settings: {
          apiKey: '2612345678901',
        },
      },
    },
  },
});
```

Add to your `flow.json` destinations:

```
"destinations": {
  "pinterest": {
    "package": "@walkeros/web-destination-pinterest",
    "config": {
      "consent": { "marketing": true },
      "loadScript": true,
      "settings": {
        "apiKey": "2612345678901"
      }
    }
  }
}
```

[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 |
| ---------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `apiKey*`  | `string`  | Your Pinterest Tag ID (numeric string, e.g. "2612345678901"). Found in Pinterest Ads Manager under Conversions → Pinterest Tag. Passed to pintrk("load", tagId).                                                                                                                     |      |
| `pageview` | `boolean` | Fire pintrk("page") once in init after core.js loads. Default true (matches Pinterest's base code convention). Set false when walkerOS sources already emit page view events and you would otherwise get a duplicate initial fire.                                                   |      |
| `identify` | `any`     | walkerOS mapping value resolving to enhanced matching fields: { em?: string, external\_id?: string }. em is auto-hashed by the Pinterest JS tag — do not hash before passing. Passed to pintrk("load", tagId, data) on init and pintrk("set", data) when the resolved value changes. |      |

\* Required fields

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

Per-event rules under `config.mapping`. For the standard rule fields (consent, condition, data, batch, name, policy) see [mapping](https://www.walkeros.io/docs/mapping.md).

| Property   | Type  | Description                                                                                                                                           | More |
| ---------- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
| `identify` | `any` | Per-event identity override. Resolves to { em?, external\_id? } and fires pintrk("set", data) when the resolved value differs from the current state. |      |

## Examples

### Default forward

Without a mapping the walker event name is forwarded as-is to pintrk track with an event\_id for dedup.

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": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000100",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000100,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Out

```
pintrk("track", "page view", {
  "event_id": "ev-1700000100"
})
```

### Identify only

A user update fires pintrk set for enhanced matching without a track call via mapping silent.

Event

```
{
  "name": "user update",
  "data": {
    "id": "usr_456",
    "email": "new@example.com"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000108",
  "trigger": "test",
  "entity": "user",
  "action": "update",
  "timestamp": 1700000108,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "silent": true,
  "settings": {
    "identify": {
      "map": {
        "em": "data.email",
        "external_id": "data.id"
      }
    }
  }
}
```

Out

```
pintrk("set", {
  "em": "new@example.com",
  "external_id": "usr_456"
})
```

### Checkout

A completed order fires Pinterest checkout with value, order\_id, currency, and a nested line\_items array.

Event

```
{
  "name": "order complete",
  "data": {
    "id": "0rd3r1d",
    "currency": "EUR",
    "shipping": 5.22,
    "taxes": 73.76,
    "total": 555
  },
  "context": {
    "shopping": [
      "complete",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "ers",
        "name": "Everyday Ruck Snack",
        "color": "black",
        "size": "l",
        "price": 420
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "product",
      "data": {
        "id": "cc",
        "name": "Cool Cap",
        "size": "one size",
        "price": 42
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    },
    {
      "entity": "gift",
      "data": {
        "name": "Surprise"
      },
      "context": {
        "shopping": [
          "complete",
          0
        ]
      },
      "nested": []
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000106",
  "trigger": "load",
  "entity": "order",
  "action": "complete",
  "timestamp": 1700000106,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "checkout",
  "data": {
    "map": {
      "value": "data.total",
      "order_id": "data.id",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "line_items": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>{var t;return\"number\"==typeof(null==(t=null==e?void 0:e.data)?void 0:t.price)}"
            },
            "map": {
              "product_id": "data.id",
              "product_name": "data.color",
              "product_price": "data.price",
              "product_quantity": {
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
```

Out

```
pintrk("track", "checkout", {
  "value": 555,
  "order_id": "0rd3r1d",
  "currency": "EUR",
  "line_items": [
    {
      "product_id": "ers",
      "product_name": "black",
      "product_price": 420,
      "product_quantity": 1
    },
    {
      "product_id": "cc",
      "product_price": 42,
      "product_quantity": 1
    }
  ],
  "event_id": "ev-1700000106"
})
```

### Page visit

A mapping renames the walker event to the Pinterest standard pagevisit event for conversion tracking.

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": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000102",
  "trigger": "load",
  "entity": "page",
  "action": "view",
  "timestamp": 1700000102,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "pagevisit"
}
```

Out

```
pintrk("track", "pagevisit", {
  "event_id": "ev-1700000102"
})
```

### Add to cart

A product add fires Pinterest addtocart with value, currency, and a single-item line\_items array.

Event

```
{
  "name": "product add",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "intent",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000105",
  "trigger": "click",
  "entity": "product",
  "action": "add",
  "timestamp": 1700000105,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "addtocart",
  "data": {
    "map": {
      "value": "data.price",
      "order_quantity": {
        "value": 1
      },
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "line_items": {
        "set": [
          {
            "map": {
              "product_id": "data.id",
              "product_name": "data.color",
              "product_price": "data.price",
              "product_quantity": {
                "value": 1
              }
            }
          }
        ]
      }
    }
  }
}
```

Out

```
pintrk("track", "addtocart", {
  "value": 420,
  "order_quantity": 1,
  "currency": "EUR",
  "line_items": [
    {
      "product_id": "ers",
      "product_name": "black",
      "product_price": 420,
      "product_quantity": 1
    }
  ],
  "event_id": "ev-1700000105"
})
```

### View content

A product view fires Pinterest viewcontent with value, currency, product\_id, and product\_name.

Event

```
{
  "name": "product view",
  "data": {
    "id": "ers",
    "name": "Everyday Ruck Snack",
    "color": "black",
    "size": "l",
    "price": 420
  },
  "context": {
    "shopping": [
      "detail",
      0
    ]
  },
  "globals": {
    "pagegroup": "shop"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000104",
  "trigger": "load",
  "entity": "product",
  "action": "view",
  "timestamp": 1700000104,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "viewcontent",
  "data": {
    "map": {
      "value": "data.price",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "product_id": "data.id",
      "product_name": "data.color"
    }
  }
}
```

Out

```
pintrk("track", "viewcontent", {
  "value": 420,
  "currency": "EUR",
  "product_id": "ers",
  "product_name": "black",
  "event_id": "ev-1700000104"
})
```

### Search

A site search fires Pinterest search with the search\_query field resolved from event data.

Event

```
{
  "name": "site search",
  "data": {
    "query": "leather jacket"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000103",
  "trigger": "test",
  "entity": "site",
  "action": "search",
  "timestamp": 1700000103,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

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

Out

```
pintrk("track", "search", {
  "search_query": "leather jacket",
  "event_id": "ev-1700000103"
})
```

### Lead with matching

A user login fires pintrk set for enhanced matching and then a lead conversion track call.

Event

```
{
  "name": "user login",
  "data": {
    "id": "usr_123",
    "email": "jane@example.com"
  },
  "context": {
    "dev": [
      "test",
      1
    ]
  },
  "globals": {
    "lang": "elb"
  },
  "custom": {
    "completely": "random"
  },
  "user": {
    "id": "us3r",
    "device": "c00k13",
    "session": "s3ss10n"
  },
  "nested": [
    {
      "entity": "child",
      "data": {
        "is": "subordinated"
      }
    }
  ],
  "consent": {
    "functional": true
  },
  "id": "ev-1700000107",
  "trigger": "test",
  "entity": "user",
  "action": "login",
  "timestamp": 1700000107,
  "timing": 3.14,
  "source": {
    "count": 1,
    "trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
    "type": "collector",
    "schema": "4"
  }
}
```

Mapping

```
{
  "name": "lead",
  "settings": {
    "identify": {
      "map": {
        "em": "data.email",
        "external_id": "data.id"
      }
    }
  },
  "data": {
    "map": {
      "lead_type": {
        "value": "login"
      }
    }
  }
}
```

Out

```
pintrk("set", {
  "em": "jane@example.com",
  "external_id": "usr_123"
});

pintrk("track", "lead", {
  "lead_type": "login",
  "event_id": "ev-1700000107"
})
```

## Standard event taxonomy[​](#standard-event-taxonomy "Direct link to Standard event taxonomy")

Pinterest expects lowercase concatenated event names. The destination never auto-maps. Every conversion event needs an explicit `mapping.name`.

| walkerOS event   | Pinterest event | Notes                                                                              |
| ---------------- | --------------- | ---------------------------------------------------------------------------------- |
| `page view`      | `pagevisit`     | Fired automatically by `pintrk('page')` on init unless `settings.pageview: false`. |
| `product view`   | `viewcontent`   | Single product. Use `value`, `currency`, `product_id`, `product_name`.             |
| `product add`    | `addtocart`     | Single product. Wrap in a `line_items` array if you also want item-level data.     |
| `order complete` | `checkout`      | Multi-product. Use `mapping.data.line_items.loop` to iterate `event.nested`.       |
| `site search`    | `search`        | Use `search_query` field.                                                          |
| `user login`     | `lead`          | Optional `lead_type`. Combine with `settings.identify` for enhanced matching.      |
| `user signup`    | `signup`        | Same identify pattern as `lead`.                                                   |
| (custom)         | `custom`        | Send Pinterest's `custom` event for non-standard conversions.                      |

## Enhanced matching[​](#enhanced-matching "Direct link to Enhanced matching")

Pinterest's web tag accepts two enhanced matching fields, both auto-hashed by the JS tag with SHA-256:

| Field         | Source                             | Notes                                                   |
| ------------- | ---------------------------------- | ------------------------------------------------------- |
| `em`          | `data.email` / `user.email` / etc. | Pinterest auto-hashes. Pass raw email, do NOT pre-hash. |
| `external_id` | `data.id` / `user.id`              | Stable user identifier. Auto-hashed by Pinterest.       |

The destination strictly limits to these two fields. CAPI-only fields (`ph`, `fn`, `ln`, `address`, `country`, `ip`, `ua`) belong to the future server destination and are intentionally not accepted here.

Identity is diffed against the destination's runtime state, and `pintrk('set', ...)` only fires when the resolved identity actually changes. The destination-level `settings.identify` is resolved lazily on the first event (init has no event to bind to), so `pintrk('load', tagId)` is called without an identity object.

## Consent[​](#consent "Direct link to Consent")

Pinterest is an advertising platform. The walkerOS consent key is **`marketing`** (not `analytics`):

```
config: {
  consent: { marketing: true },
  loadScript: true,
  settings: { apiKey: '2612345678901' },
}
```

The walkerOS `config.consent` gate blocks unconsented events from reaching the destination in the first place. **Pinterest has no `opt_in`/`opt_out` SDK API**, so the destination implements consent revocation as a runtime suppression flag:

1. `on('consent')` reads `config.consent` to determine which keys to check.
2. If any required key resolves to `false`, the destination flips `_state.consentGranted = false` and silently suppresses all subsequent `pintrk('track', ...)` calls.
3. If consent is later re-granted (all required keys `true`), the flag flips back and tracking resumes.

The Pinterest Tag itself stays loaded throughout. Only the walkerOS bridge goes silent.

Auto page view

The destination fires `pintrk('page')` once on init by default to match Pinterest's base code convention. Set `settings.pageview: false` if your walkerOS sources already emit page view events that you map to `pagevisit`, which prevents a duplicate initial fire.

## Future: Conversions API[​](#future-conversions-api "Direct link to Future: Conversions API")

A server-side Pinterest Conversions API destination is planned as a follow-up, matching the Meta / TikTok / LinkedIn web+server split. It will share the `event_id` field with this web destination for cross-channel deduplication.

## Related[​](#related "Direct link to Related")

* [Pinterest Tag documentation](https://help.pinterest.com/en/business/article/install-the-pinterest-tag)
* [Enhanced match documentation](https://help.pinterest.com/en/business/article/enhanced-match)
* [Bundled mode](https://www.walkeros.io/docs/getting-started/modes/bundled.md)