Conversions API
Send server-side events to Pinterest with POST /v1/ads/conversions and read their Event Quality Score.
Send server-side events to Pinterest with POST /v1/ads/conversions on your pinterestads account. It maps to Pinterest's POST /v5/ad_accounts/{id}/events.
Events deduplicate against the Pinterest tag by eventId, the same id the Shopify install sends.
| Field | |
|---|---|
destinationId | The numeric ad account id: Pinterest attributes to the ad account, not to a tag. GET /v1/accounts/{accountId}/conversion-destinations lists them. |
eventName | Standard names map to Pinterest's: Purchase = checkout, AddToCart, InitiateCheckout, AddPaymentInfo, Lead, CompleteRegistration = signup, Subscribe, ViewContent, Search, PageView = page_visit. Any other string is sent as is, so it matches a custom event of that name. |
user | Needs email, or ipAddress plus userAgent. Identifiers are hashed before they leave Zernio. |
user.clickIds.epik | The epik click id (the _epik cookie), sent as click_id. |
actionSource | web stays web; offline, crm, phone_call, system_generated and business_messaging become offline. App events need platformData.action_source app_android or app_ios. |
testCode | Any value sends the batch with test=true: Pinterest validates it without recording it. |
consent.adUserData: "DENIED" | Sets opt_out on every event. |
const { data } = await zernio.conversions.sendConversions({
body: {
accountId: '66b2e19d8c3f5a7e9d0b1c2d',
destinationId: '549755885175',
events: [{
eventName: 'Purchase',
eventTime: 1804150800,
eventId: 'order_1042',
value: 59.9,
currency: 'USD',
user: { email: 'ana@example.com', clickIds: { epik: 'dj0yJnU9...' } }
}]
}
});Response (200):
{
"platform": "pinterestads",
"eventsReceived": 1,
"eventsFailed": 0,
"failures": []
}Pinterest answers per event, so one bad event does not fail the batch. Failed events are listed in failures:
INVALID_EVENT: an event without an identity, caught before sendingPINTEREST_EVENT_FAILED: an event Pinterest rejects
The connected Pinterest user needs a Business Access role on the ad account (403 otherwise).
Event Quality Score
Call this endpoint (reference):
GET /v1/ads/conversions/quality?accountId=...&destinationId=<ad account id>It returns Pinterest's Event Quality Score for Conversions API web events over the last 14 days:
- one row per event name
- each identifier's coverage in
matchKeys eventCoveragePercentage, the share of events whoseevent_idoverlaps with the tag
Pinterest has no composite score, so compositeScore is absent.