Website conversions
Use Conversions in the advertiser dashboard to create a NotPixel Pixel, receive website events, and select a campaign’s primary conversion. Standard events and custom event names are discovered automatically. You do not need to create a custom conversion before sending lead, purchase, or another event.
Review event activity
The Total events chart shows unique website events received per day over the last 7, 30, or 90 days, including today, in UTC. Browser and CAPI deliveries with the same event identity count once. Days without events appear as zero.
On Data sources, the chart includes all sources in the account. On the other tabs, it follows the selected Pixel. The source table still labels its event count as Events (7 days), and the event stream shows the latest 100 events from the past seven days.
Install the Pixel
In Conversions → Data sources, select Create, enter a name and your exact website origins (such as https://shop.example.com), and save. The installation dialog opens automatically with the new Pixel ID and Copy code. Install the setup code once per page in your HTML head:
You can reopen this dialog from the source row’s ⋯ → View code menu. Use Edit to change the name or allowed origins, Conversions API to manage server tokens, and Archive to stop collection while preserving history. The installation dialog also links to the source’s Event stream.
<script>
!function(w,d){if(w.npx)return;var q=function(){q.q.push(arguments)};q.q=[];w.npx=q;
var s=d.createElement('script');s.async=true;s.src='https://connect.notpixel.ai/npevents.js';
d.head.appendChild(s);}(window,document);
npx('init', 'YOUR_PIXEL_ID');
</script>The Pixel starts with measurement disabled. After your consent manager confirms consent, call:
npx('consent', 'granted');This captures URL npclid into a first-party click cookie, creates a separate browser cookie, and sends one page_view. Actual cookie names are _npc_<pixelId> and _npb_<pixelId> (with an additional _test suffix in test mode). Cookies are configured for 30 days and are scoped to the current host by default. Browser policies can shorten their lifetime.
To revoke consent, clear both cookies and request removal of the browser’s attribution links:
npx('consent', 'denied', function (forgotten) {
// false means the network removal request could not be confirmed.
});Send business events explicitly when the action succeeds. Do not fire purchase simply because a checkout page opens.
npx('track', 'lead', { eventId: 'lead_123' });
npx('track', 'purchase', {
eventId: 'order_123',
value: '199.90',
currency: 'BRL',
customData: { product_category: 'software' }
});Supported standard names include page_view, view_content, search, add_to_cart, initiate_checkout, add_payment_info, lead, purchase, complete_registration, subscribe, start_trial, contact, and schedule. Custom names use lowercase snake_case, up to 64 characters.
The Pixel reads the current page path and click reference. It does not scrape forms or automatically collect contact information. Do not send personal data through custom properties or event IDs.
Conversions API
Generate an API token inside the Pixel’s settings. Store it on your server. Tokens are shown once and can be revoked independently.
Capture consented attribution context with the lead or order, so your backend can use it when a later webhook confirms the conversion:
npx('getContext', function (context) {
const attribution = Object.fromEntries(
Object.entries(context).filter(([, value]) => value !== null)
);
// Save attribution with the lead or order through your own authenticated API.
// The context is { npc, npb }; neither value is a server API token.
});npc carries the click reference. npb identifies the browser within this Pixel’s scope. eventId identifies the business action. Do not generate a new browser identifier for each event. Calling getContext without a callback returns the current context synchronously; before consent or initialization it returns null values. Omit null fields from CAPI events.
Your backend can also send conversions without browser JavaScript: preserve the raw URL npclid under your consent policy and send it as npc. Without a browser identifier, attribution relies on that explicit click reference.
Send the saved context from your server:
const response = await fetch('https://api.notpixel.ai/api/v1/conversions/events', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NOTPIXEL_CONVERSIONS_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
pixelId: 'YOUR_PIXEL_ID',
events: [{
eventName: 'purchase',
eventId: 'order_123',
eventTime: new Date().toISOString(),
...order.notpixelAttribution, // saved npc and/or npb; omit null values
value: '199.90',
currency: 'BRL',
sourceUrl: 'https://shop.example.com/checkout/success'
}]
})
});
const result = await response.json();
for (const event of result.results ?? []) {
if (event.status !== 'received') {
// Inspect and correct this event before retrying.
}
}Send up to 100 events per request, with a maximum body size of 128 KiB. eventTime is an ISO 8601 timestamp with a timezone; events can be up to seven days old or five minutes ahead. sourceUrl, when supplied, must belong to an origin configured on the Pixel; query parameters and fragments are discarded.
A successful HTTP response contains a result for each event. received confirms storage, while attributed, primary, and reason explain campaign attribution. An event without a valid click is still received. Malformed events are individually rejected. Retry network failures, HTTP 429 (respect Retry-After), and 5xx errors using the original event ID.
Collection limits are 3,000 requests per minute per Pixel, 600 per server token, and 120 per browser IP/Pixel. HTTP 401 indicates an invalid or revoked token; correct credentials before retrying.
Deduplication
Use the same eventName and eventId for the same business action in the Pixel and CAPI. Deduplication is scoped to the Pixel. Test events are separate from regular events.
Deduplicated receipts reject contradictory click or browser identifiers with conflicting_receipt_identifiers; they do not move the conversion or change its value. The legacy npclid event field is accepted during migration, but contradicting npc and npclid in one payload is rejected. New integrations should use npc.
The first server delivery may enrich the browser event’s monetary value and fill a missing click reference. Further retries do not create another conversion or overwrite that server value. A changed amount can also change whether an optional custom rule matches.
Attribution and campaign goals
The click URL adds npclid while preserving your existing URL parameters. The Pixel remembers the most recently captured reference for that website and Pixel. An explicit reference takes precedence. An invalid explicit reference does not fall back to the browser. If npc is omitted, npb can resolve the latest eligible real click previously linked to that browser and Pixel before the event occurred. Links are isolated by Pixel, advertiser, and test mode. An organic browser with no eligible click remains unattributed. This does not identify a person across devices.
Attribution is based on a NotPixel click for the same advertiser, with a campaign window of 1, 7, or 30 days (30 by default). There is no view-through or modeled attribution.
Choose one primary event per campaign for Conversions and CPA. Other events remain in the event stream. Optionally create a custom conversion with up to five AND conditions on the page path, event value, currency, or scalar custom properties. A monetary condition must specify its currency.
Goal changes and custom rule edits create new versions and apply to events occurring after the change. Late events use the definition effective when they occurred. Goals are locked while a related experiment is running or paused.
Values remain in their original currencies. USD ad spend is used for CPA; ROAS is available in reporting data only when all primary conversions have comparable USD values. No implicit currency conversion is applied.
Own subdomains and checkout domains
For your own subdomains, explicitly choose the parent domain:
npx('init', 'YOUR_PIXEL_ID', { cookieDomain: 'example.com' });Register every exact origin in the Pixel settings. Use this configuration consistently on your own subdomains. The default is host-only; do not use a parent domain shared by unrelated customers.
For a checkout on another domain, configure the same Pixel on both sites, register both exact origins, and opt in to the checkout destination:
// On https://shop.example.com
npx('init', 'YOUR_PIXEL_ID', {
linkedOrigins: ['https://checkout.example.net']
});After consent, ordinary same-tab links to that origin receive a short-lived encrypted _npl token. The destination Pixel restores the context after consent and removes _npl from the URL. Tokens are limited to the destination origin, Pixel and test mode, expire after two minutes, and work once. Modified clicks, downloads, forms and new-tab links are not automatically decorated. A failed context transfer falls back to ordinary navigation; navigation waits at most about 2.5 seconds.
For a custom checkout button or form, prepare the link explicitly:
npx('link', 'https://checkout.example.net/pay?order=123', function (url) {
window.location.assign(url || 'https://checkout.example.net/pay?order=123');
});Configure linkedOrigins only for domains you control or a checkout that supports your Pixel integration. The helper does not bypass destination consent. For payment providers where you cannot install the Pixel, associate context with your order before redirecting and send the confirmed conversion through CAPI.
Consent withdrawal on the server
Stop sending the saved context when consent is withdrawn, and remove it from your own lead/order records. You can also revoke its attribution links through CAPI:
await fetch('https://api.notpixel.ai/api/v1/conversions/forget', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NOTPIXEL_CONVERSIONS_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({pixelId: 'YOUR_PIXEL_ID', npb: savedContext.npb})
});Historical conversion totals remain. Reusing a revoked browser identifier is rejected. A new consent grant creates a fresh browser context; previous browser links are not transferred.
Test and troubleshoot
Generate a test code in Conversions and initialize the Pixel with it:
npx('init', 'YOUR_PIXEL_ID', { testEventCode: 'YOUR_TEST_CODE' });For CAPI, add testEventCode alongside pixelId and events. Codes expire after 15 minutes. Enable Test events in the dashboard to inspect them. They never increase campaign conversions, value, or experiment results.
The event stream shows the latest 100 events received in the past seven days. Diagnostics show identifier coverage for the past seven days and distinguish missing references, unlinked or expired browsers, invalid references, events outside the window, missing goals, and custom rules that did not match. The stream shows whether attribution used an explicit click or a previously linked browser. Conflicting deliveries are counted separately. Raw browser identifiers are not displayed. Receipt and attribution are separate: a received event is not necessarily a primary campaign conversion.