Ask your AI

Pinterest Tag

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

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 | CLI reference

The destination loads core.js unless loadScript is false, and walkerOS injects it once per page. If your page already has the Pinterest base code, set loadScript: false, or the tag loads twice; the destination still calls pintrk('load', tagId) and, unless settings.pageview is false, pintrk('page').

Configuration

This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.

Settings

Property	Type	Description
`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`	Call pintrk("page") once in init, as Pinterest's base code does. Default true. Set false to leave the call out.
`identify`	`any`	walkerOS mapping value resolving to enhanced matching fields: { em?: string, external_id?: string }. The Pinterest tag takes em plain (it hashes it with SHA-256 in the browser) or already hashed. Resolved on each event and sent with pintrk("set", data) when it changes; init calls pintrk("load", tagId) without it.

* Required fields

Mapping

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

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,
    "value": 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.value",
      "order_id": "data.id",
      "currency": {
        "key": "data.currency",
        "value": "EUR"
      },
      "line_items": {
        "loop": [
          "nested",
          {
            "condition": {
              "$code": "e=>\"object\"==typeof e&&null!==e&&\"data\"in e&&\"object\"==typeof e.data&&null!==e.data&&\"price\"in e.data&&\"number\"==typeof e.data.price"
            },
            "map": {
              "product_id": "data.id",
              "product_name": "data.name",
              "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": "Everyday Ruck Snack",
      "product_price": 420,
      "product_quantity": 1
    },
    {
      "product_id": "cc",
      "product_name": "Cool Cap",
      "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.name",
              "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": "Everyday Ruck Snack",
      "product_price": 420,
      "product_quantity": 1
    }
  ],
  "event_id": "ev-1700000105"
})

View content

A product view fires Pinterest viewcontent with value, currency, and a single-item line_items array.

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"
      },
      "line_items": {
        "set": [
          {
            "map": {
              "product_id": "data.id",
              "product_name": "data.name",
              "product_price": "data.price"
            }
          }
        ]
      }
    }
  }
}

Out

pintrk("track", "viewcontent", {
  "value": 420,
  "currency": "EUR",
  "line_items": [
    {
      "product_id": "ers",
      "product_name": "Everyday Ruck Snack",
      "product_price": 420
    }
  ],
  "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

Pinterest expects lowercase concatenated event names. The destination does not translate event names, so every conversion event needs an explicit mapping.name. An event without a rule is sent under its walkerOS name, which is no Pinterest standard event (pintrk('track', 'product view', { event_id })). To send only the events you map, add a wildcard rule with ignore: true ('*': { '*': { ignore: true } }).

walkerOS event	Pinterest event	Notes
`page view`	`pagevisit`	Separate from the base code's `pintrk('page')` call the destination makes on init.
`product view`	`viewcontent`	Single product. `value`, `currency`, and the product in a one-item `line_items` array.
`product add`	`addtocart`	Single product. Product fields (`product_id`, `product_name`, ...) go in `line_items`.
`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

Pinterest's web tag accepts two enhanced matching fields:

Field	Source	Notes
`em`	`data.email` / `user.email` / etc.	Plain or hashed. The Pinterest tag hashes a plain email with SHA-256 in the browser.
`external_id`	`data.id` / `user.id`	Stable user identifier, sent as resolved.

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

Identity is diffed against the destination's runtime state, and pintrk('set', ...) fires only when the resolved identity 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.

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

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

Until marketing is granted, the destination does not load the Pinterest Tag and the collector holds its events in a queue. They are sent once consent is granted, see consent management. After a revocation, walkerOS holds new events again until the next grant. The destination does not tell the loaded tag: Pinterest's consent call pintrk('setconsent', false) deletes the tag's first-party cookies and storage, and the destination never makes it, so the tag stays in the page and keeps them.

Auto page view

The destination fires pintrk('page') once on init by default to match Pinterest's base code convention. Set settings.pageview: false to leave it out.

Conversions API

The server Pinterest destination sends conversions through the Conversions API. Both destinations send the event's id as event_id, unless a rule's data maps its own event_id, which replaces it. Give an event the same Pinterest event name and event_id on both sides so Pinterest can deduplicate it.

💡 Need implementation support?

elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)

Installation​

Configuration​

Settings​

Mapping​

Examples

Default forward

Identify only

Checkout

Page visit

Add to cart

View content

Search

Lead with matching

Standard event taxonomy​

Enhanced matching​

Consent​

Conversions API​

Related​

Installation

Configuration

Settings

Mapping

Standard event taxonomy

Enhanced matching

Consent

Conversions API

Related