ads

POST /v1/public/ads-wordpress/heartbeat

The plugin reports in and reads its config.

All ads endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

This endpoint does not take an API key. It takes its own credential, issued to the plugin or service that calls it, as a bearer token; see the description above.

This endpoint takes no organisation id. Your key already identifies the organisation it belongs to, and the response is scoped to it.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/public/ads-wordpress/heartbeat \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{  }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Site token only. Records the plugin and WordPress versions, whether Cloudflare fronts the site, the tag mode and, per UTC day, how many purchases the plugin sent through Zaraz (zaraz_sent, running totals; days in the future or older than 35 days are dropped). WPPAID: also each path's own per-day counts, so the dashboard measures the browser path and the server upload apart — zaraz_delivered (handed to Zaraz in the visitor's browser), zaraz_declined (withheld: no ad consent) and orders_reported (paid orders queued for the server upload). A counter not sent keeps what it had. The site calls us; nothing calls the site (§2.56).

Request body

NameTypeRequiredWhat it is
plugin_versionstringNo—
wp_versionstringNo—
cloudflarebooleanNo—
modestring<browser, zaraz>No—
zaraz_sentobjectNo{"YYYY-MM-DD": purchases sent through Zaraz that day}
zaraz_deliveredobjectNo{"YYYY-MM-DD": of those, handed to Zaraz in the browser}
zaraz_declinedobjectNo{"YYYY-MM-DD": of those, withheld because the visitor declined ad cookies}
orders_reportedobjectNo{"YYYY-MM-DD": paid orders queued for the server-side upload}

Response

NameTypeRequiredWhat it is
site_idstringYes—
site_hoststringYes—
modestring<browser, zaraz>Yes—
cloudflare_detectedbooleanYes—
offer_zarazbooleanYes—
heartbeat_secondsintegerYes—
tagobjectNoThe site's Zinn® Ads tag (the same AdsSiteTag "Install on any site" edits; claiming a host creates or links it). Browser mode loads script_url and hands each conversion to it.…
ref_prefixstringNoThe site's order-reference prefix: an order's transaction id is <ref_prefix>-<order number> in the browser tag and the server-side upload alike.
shieldobjectYes—

Errors this endpoint can return

401 · 429