Declare Where Your Pixel Runs

Summary: Every website pixel declares where it runs: a list of your sites, or any site. Visitors are identified only on the sites you list, or on any site if you choose that. Declare it when you create the pixel, in the dashboard or through the API.

Choose One

Choice	When to use it	What you send
My websites	You know the sites the pixel goes on.	`allowed_origins`: the sites, such as `["example.com", "shop.example.com"]`
Any site	One pixel runs on many sites you do not list ahead of time, such as an agency installing the same pixel across client sites.	`"allow_any_origin": true`

List every hostname the pixel loads on. example.com and shop.example.com are different sites, so list both if the pixel runs on both.

Choose Any site only when you cannot list the sites. Anyone who copies the pixel's snippet onto their own site can send data to your pixel.

In the Dashboard

When you create a pixel, the Where will this pixel run? step asks you to choose:

My websites: paste your sites, one per line or separated by commas.
Any site I put it on: for agencies and pixels placed on many sites.

You can change the list later in the pixel's settings.

Through the API

Create the pixel with POST /api/v2/pixel/create and send exactly one of the two fields:

curl -X POST https://api.delivr.ai/api/v2/pixel/create \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "X-Api-Secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "title": "My Website Pixel",
    "allowed_origins": ["example.com", "shop.example.com"]
  }'

For any site, replace allowed_origins with "allow_any_origin": true.

The response repeats the declaration as stored:

{
  "response": {
    "pixel_id": "8a755c42-b2b1-...",
    "installation_url": "https://cdn.delivr.ai/pixels/8a755c42-b2b1-.../p.js",
    "allowed_origins": ["example.com", "shop.example.com"],
    "allow_any_origin": false,
    "origins_status": "declared"
  }
}

origins_status is declared when the pixel lists its sites or allows any site, and unverified when it declares neither.

What Delivr Accepts

You can send a domain (example.com) or a full URL (https://Shop.Example.com/pricing). Delivr keeps the lowercase hostname and drops repeats. A pixel can list up to 500 sites.

These are refused with a 400 that names the entry to fix:

IP addresses, such as 203.0.113.10
localhost
A name with no dot, such as intranet
A bare suffix, such as co.uk
Wildcards, such as *.example.com

Error code	Meaning
`request.allowed_origins.required`	v2 only: neither field was sent, or the list was empty.
`request.allowed_origins.conflict`	v2 only: both a list and `allow_any_origin: true` were sent.
`request.allowed_origins.invalid`	An entry was refused. The message names it, for example `allowed_origins[1] "203.0.113.10": is an IP address; list the site's domain instead`.

v1 Is Deprecated

POST /api/v1/pixel/create keeps working, with both fields optional, until April 24, 2027. A pixel created there without either field has no declared sites. Every v1 response carries these headers:

Deprecation: @1792800000
Sunset: Sat, 24 Apr 2027 00:00:00 GMT
Link: </api/v2/pixel/create>; rel="successor-version"

To move to v2, change the path and add allowed_origins or allow_any_origin to the body. Nothing else changes.

Next Steps

Pixel and DSP Events API: install the pixel and query its events
Understanding Resolution Rates: what to expect after you install
Create pixel (v2) reference: the full request and response schema