Pinterest Tag
Read and create Pinterest tags, manage their custom events, check stats and install them on Shopify or WordPress through the tracking tags API.
Manage Pinterest tags through the platform-neutral tracking tags API on your pinterestads account: read and create tags, manage custom events, check stats and install them.
Before you start
The connected Pinterest user needs a Business Access role on the ad account (Admin, Analyst, Audience or Campaign). Without one, calls answer 403.
Read the tag
GET .../tracking-tags lists the tags of every readable ad account. One account refusing access does not hide the others.
GET .../tracking-tags/{tagId} adds the tag's code (Pinterest's base code), lastFiredTime and installed.
const { data } = await zernio.trackingtags.getTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d', tagId: '2612345678901' }
});Response (200):
{
"platform": "pinterestads",
"tag": {
"id": "2612345678901",
"siteTagId": "2612345678901",
"name": "Storefront tag",
"platform": "pinterestads",
"kind": "tag",
"status": "active",
"lastFiredTime": null,
"installed": false,
"ownerAdAccountId": "549755885175",
"code": "<script type=\"text/javascript\">...pintrk('load', '2612345678901');...</script>"
}
}| Field | Value |
|---|---|
id | The numeric Pinterest tag id. It is also what the on-site code loads, so siteTagId equals id. |
adAccountId | The numeric ad account id. A tag belongs to one ad account; without adAccountId, per-tag calls find the owner across every ad account the connection can read. |
kind is tag.
Create a tag
POST .../tracking-tags takes a name and, optionally, automaticMatchingFields.
const { data } = await zernio.trackingtags.createTrackingTag({
path: { accountId: '66b2e19d8c3f5a7e9d0b1c2d' },
body: { adAccountId: '549755885175', name: 'Storefront tag' }
});Response (201):
{
"platform": "pinterestads",
"tag": {
"id": "2612345678901",
"siteTagId": "2612345678901",
"name": "Storefront tag",
"platform": "pinterestads",
"kind": "tag",
"status": "active",
"lastFiredTime": null,
"installed": false,
"ownerAdAccountId": "549755885175",
"code": "<script type=\"text/javascript\">...pintrk('load', '2612345678901');...</script>"
}
}automaticMatchingFields switches on automatic enhanced match for those fields (em, ph, fn, ln, ct, st, zp, country, external_id, ...).
Create is the only time Zernio can set it, because Pinterest cannot edit a tag afterwards.
Tag operations
| Operation | Behavior |
|---|---|
Stats (GET .../stats) | No time range (startTime/endTime answer 400). Rows: the tag (lastFiredTime, status, enhancedMatchStatus), the events Pinterest has seen on it (page_visit and ocpm_eligible sources, with the matching siteEvent), and the ad account's Event Quality Score for the last 1 and 14 days. An account Pinterest cannot score yet reports why in its row. |
| Update | 501: API v5 only creates, lists and reads conversion tags (PATCH and PUT answer 405); rename a tag or change enhanced match in Pinterest Ads Manager. |
| Share | 501: a tag belongs to one ad account; use Pinterest Business Access. |
Conversion events (.../events) | Pinterest's advertiser defined events: a custom event name the site sends, mapped to a standard type. List, create (name plus type or siteEvent), update (only the type: the name is the event's id, so it cannot be renamed) and delete (Pinterest stops tracking it, state: "disabled"). They belong to the ad account, so every tag of that account lists the same ones. At most 15 per ad account, names of 1 to 100 letters, digits, _ or -, case-insensitive. type is one of Pinterest's optimizable types (CHECKOUT, ADD_TO_CART, LEAD, SIGNUP, PAGE_VISIT, ...). |
| Diagnostics, users and partners | 501. |
| Delete | Not offered: DELETE on a conversion tag answers 405 at Pinterest. |
| Install | Shopify and WordPress. WordPress gets Pinterest's base code with pintrk('page') and a pagevisit event (official fallback: Pinterest for WooCommerce, WooCommerce stores only). Shopify sends every storefront event to ct.pinterest.com/v3/, the endpoint Pinterest's noscript tag and core.js use, with core.js's parameter names, the epik click id kept in _epik and event_id set for dedup with the Conversions API. |
Install targets: a connected Shopify store or WordPress site.
If it fails
| Error | Cause | Fix |
|---|---|---|
403 | The Pinterest user lacks a Business Access role on the ad account | Grant Admin, Analyst, Audience or Campaign access in Pinterest Business Access. |
400 on stats | startTime or endTime sent | Drop them: tag stats take no time range. |
501 on an update | Pinterest's API cannot edit a tag | Rename it or change enhanced match in Pinterest Ads Manager. |
| A second tag after a retry | The create is not idempotent | List the tags after a timeout instead of retrying. |
Related
- Pixels and tracking tags: the tag API across platforms.
- Send a conversion event: server-side events that dedup against the tag.
- Shopify tracking pixels: the storefront install.