Server-side tracking

When to go server-side#

The browser tag sees what happens on the page. Part of your business reality happens off the page: the payment gateway posts the result to your server, a subscription renews overnight, a support agent enters an order by hand, or the customer closes the browser before the gateway's response arrives.

Both paths write to the same event table and feed the same identity graph. You do not have to give up one for the other — but do not send one event down both, because the two paths use different IDs and you will get two independent rows.

Create a server key#

A server key is bound to a property and is created from any data stream's panel.

There are four scopes. Grant the smallest set that works:

Creating a key requires editor level or above; listing keys needs only report-read access — but the list shows the prefix, never the secret.

Send your first event#

The base address is https://api.adpix.io/api/v1/s2s. Every request carries two things: the key in the Authorization header and the property ID in the X-Sov-Site header.

curl -X POST https://api.adpix.io/api/v1/s2s/events \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>' \
  -H 'Content-Type: application/json' \
  -d '{
    "event": "purchase",
    "event_id": "order_10482",
    "order_id": "10482",
    "email": "ali@example.com",
    "value": 4900000,
    "currency": "IRR",
    "properties": { "gateway": "saman" }
  }'

{
  "accepted": true,
  "event_id": "order_10482",
  "global_user_id": "...",
  "anonymous_linked": true,
  "attribution_snapshot": { "channel": "Paid Search", "attribution_model": "last_non_direct" },
  "request_id": "req_..."
}

Before wiring everything up, call POST /api/v1/s2s/verify once. If the key and the property match, the response returns the property's name and timezone, the key's scopes, the attribution window length, and whether HMAC is required — exactly what you need to debug a configuration.

Of the body fields, only event and event_id are required. value and currency carry revenue (the currency code must be three uppercase letters), items builds the order lines, and anything else goes in properties to be available in reports as event parameters.

event_id — the guarantee an order is not counted twice#

This is the most important rule on the page. You choose the event_id, and it must stably identify that same event in your system — order_10482, not a fresh random number on each attempt.

AdPix keeps the first response for each event_id along with a fingerprint of the request body. After that:

So a network retry, a re-run of a job queue and a restart mid-way are all safe. This is the only collection path in AdPix that offers that guarantee; the browser does not.

Link the visitor to the real user#

Every event has to say who it is about. You have four ways, and you can send more than one together:

• anonymous_id — the anonymous ID the browser created. Send it and the behaviour from before the user signed in attaches to the same person.
• external_id — the user's ID in your own system (a CRM customer ID, a panel user ID).
• email — deterministic.
• phone — deterministic and at parity with email. The number is normalised to international form using the property's default calling code, so the national form 0912… and the international form of the same number reach one user.

Email, phone and external ID are deterministic links and are never overwritten by a browser-fingerprint guess. For the moment of sign-in or sign-up — where you have no business event yet — call POST /identify; it establishes the same link and returns the global user ID, the linked anonymous IDs and their current attribution. The full logic is in How AdPix identifies visitors.

Orders and the attribution snapshot#

If you send an order_id (or name the event purchase, order_updated or order_refunded and include the order ID), AdPix builds and freezes an attribution snapshot for that order: channel, source, campaign, first and last touch, days to conversion and the touch count.

The snapshot's model is last non-direct: if the last touch is direct or empty, the first touch takes its place.

The snapshot is written once. A later update to the same order brings the value and status but leaves attribution untouched — so your report is not rewritten by the customer's later behaviour. To read it:

curl 'https://api.adpix.io/api/v1/s2s/attribution?order_id=10482' \
  -H 'Authorization: Bearer sk_...' \
  -H 'X-Sov-Site: <property_id>'

Batch sending#

For a backfill or an overnight queue, send POST /events/batch with a body of {"events":[…]}. The per-request cap is 500 events; more returns a 413.

The response is a results array, in input order, one result per event. One invalid event does not take down the rest — its own result carries the error and the others are accepted. So always read results; the request's overall status code is not enough.

HMAC signing#

If you ticked "require HMAC" when creating the key, every request must also carry a signature. The signing string is <timestamp>.<raw body> and the signing key is the sk_… secret itself:

X-Sov-Timestamp: 1767225600
X-Sov-Signature: t=1767225600,v1=<hex(HMAC-SHA256)>

A clock difference of more than 300 seconds from the server returns stale_timestamp — so keep your server's clock in sync. The signature is computed over the raw body bytes, not over re-serialised JSON; if you re-serialise the body, the signature will not match.

If you send the signature headers, they are verified even when the key does not require HMAC.

What these events look like in reports#

There are a few deliberate differences from browser events. Not knowing them looks like missing data.

• They have no session. A server-side event is not a browser session and AdPix does not create one for it. If it did, every CRM order would become a new "session" and would understate conversion rate. The consequence: these events are not counted in session-based metrics (engagement rate, sessions per user), but they are fully present in event counts, key events, revenue and user attribution.
• They have no page URL. Page-based reports do not show them.
• Their attribution comes from that user's history. If you send first_touch or last_touch in context, that is used; otherwise AdPix falls back to the durable first touch it stored for that visitor from the browser path. This is why sending anonymous_id makes a difference: without it, the order is not connected to the campaign that actually produced it.
• Geography and device come from context. Send context.ip and context.user_agent to populate country and device type; omit them and those stay empty, because your server's IP is not a substitute for the user's.

Errors#

Every error returns JSON and always carries a request_id. Include it if you open a ticket.

The rate limit is counted against the key itself. If you have a heavy backfill job, create a separate key for it so it cannot block your live shop traffic.

The legacy /api/v1/track endpoint#

There is an older path that accepts the browser tag's event shape with a server key. It takes no property header, builds no attribution snapshot, and gives no guarantee about re-sending. It is kept only for older integrations; write new work against /api/v1/s2s/events.

The complete request and response shapes, for when you are writing your own client, are in the Server-to-server API reference.

Frequently asked questions#

Related#