How server side tracking works in Trace

Most of what Trace records comes from the tracking tag in the visitor’s browser. Server side tracking adds a second route: your own server tells Trace about an order or a refund without going through the visitor’s browser. This article says what exists today, how an order from your server joins the visitor’s journey, and where consent stops it.

What server side means here

In Trace, server side means that your server, or a plugin or app that runs for your shop, sends Trace an order, a refund or another event over its API. It sits beside the tracking tag and does not replace it. The tag still follows the visit and stores the visitor’s key, and that key is what lets an order from your server join the visit that led to it.

Orders reach Trace by two paths. The visitor key joins them to one visit, and the order id counts each order once.

The visitor browses your site. If they allowed analytics, the tag keeps a random visitor key in their browser.
The tag reports what happens in the browser, including the order, from the thank you page.
At checkout, the key and the request id are handed to your server with the order. Your server sends the order to Trace when payment is taken, and sends a refund if there is one.
Trace joins the two paths. The visitor key ties the order to the visit, the order id counts it once whichever path reports it, and the visitor’s consent is checked first.
The order appears in your reports as part of the journey, at its value, with any refund taken off.
If you have switched on the conversion feed, Trace can then tell your ad platform about the conversion, server to server.

What exists today

The API. Your server sends an order to POST /v1/event/purchase, a refund to POST /v1/event/refund and any other event to POST /v1/event. The address is https://app.usetrace.io/api-proxy, and each request carries your site’s tracking key in the x-trace-api-key header.
The WooCommerce plugin. The Trace Analytics plugin sends each paid order from your server, in the background, so a slow Trace never holds up a payment. If Trace cannot be reached it tries again later, up to three more times. It does not send refunds today. Install the Trace WordPress plugin has the steps.
The Shopify app. The Trace Shopify app sends each paid order from Shopify, and sends the order’s new value when it is refunded. It is installed from a private link that Trace sends you, not from the Shopify App Store. Install the Trace Shopify app says how to get one.

The order code you add to Shopify’s customer events, and the tag’s reading of a WooCommerce thank you page, run in the visitor’s browser. They belong to the browser path, not the server path.

What your server sends

An order carries:

The order id, your own reference for the order.
The value: what the customer paid for the order, after any discount.
The currency and the time of the order.
The visitor key and the request id, when your checkout has them. They are what join the order to a visit.
A discount code and the discount it gave, when the order used one. Trace reads the code as text.

Trace never needs a name, an email address, a phone number or an address, and it does not match visitors on an email address, a customer id or a hash of either. The visitor key and the request id are the only ways a server order joins a journey.

An event sent to /v1/event takes the same fields as the tag: the event type, the page path, the referrer, the campaign fields, a value and a time. Your server also states the visitor’s consent with each one, as GRANTED, DENIED or UNKNOWN.

How an order joins the visitor’s journey

The tag stores a random visitor key in the visitor’s browser, under trace_id in local storage or trace_auk in session storage, once they have allowed analytics. It also keeps a request id for the tab under trace_rid in session storage.
Your checkout reads them and hands them to your server with the order. The WooCommerce plugin does this on both the classic checkout and the checkout block, and deletes them from the order once it has been sent.
Your server sends the order with the key and the request id.
Trace adds the order to the visitor’s latest journey if that journey was active in the 30 days before the order, which is the default. The order becomes the journey’s conversion, at its value, and Trace works out the channels’ credit as it does for any conversion.
After a longer gap, the order starts a new journey with no earlier visits and no ad click.

One order, counted once

Trace counts an order once for your site by its order id, however many routes report it. The tag’s thank you page, Shopify’s checkout code, your server and a retry of any of them all give one order.

The ids have to match. The WooCommerce plugin and the tag both use the WooCommerce order number. The Shopify app and Shopify’s checkout code both use Shopify’s numeric order id. If your own page and your own server name one order differently, Trace has no way to know they are the same.
Sending an order again does not add a second order. The order keeps the value it was first recorded with on its journey. To lower a value, send a refund.

A server order follows the same consent rules as the tag. Your server cannot make a visitor consent. Your site’s country, set when you add the site, decides which rules apply, and a site with no country set is treated as UK and EU. How consent flags work has the full rules.

The order	UK and EU	United States and Other
The visitor allowed analytics and the order carries their key	Recorded on their journey.	Recorded on their journey.
The visitor refused	Not recorded and not counted.	Not recorded and not counted.
The visitor has not answered, and the order carries a visitor key	Held for up to 60 minutes. If the visitor accepts in that time, and the order carried the request id from their tab, it joins their journey. Otherwise it is deleted and not counted anywhere.	Recorded on their journey, because consent is assumed on these sites until a visitor refuses.
The order carries no visitor key	Held for up to 60 minutes. If the visitor accepts in that time, and the order carried the request id from their tab, it joins their journey. Otherwise it is deleted and not counted anywhere.	Held for up to 60 minutes, then counted in the anonymous totals with its value, and joined to no journey. If the visitor accepts in that time and the order carried the request id from their tab, it joins their journey instead.

What this means in practice:

On a UK or EU site, a server order is recorded only for a visitor who allowed analytics. An order from a visitor who blocked the tag, never saw the banner or has not answered is not recorded. It is not counted anonymously either. Trace counts anonymous visits only for visitors it can place in the UK, and it places them by their connection. A server’s connection is its own, so Trace cannot place the visitor, and it counts nothing.
An order with no key cannot join a journey. Shopify’s paid order webhook always sends none, so on a UK or EU site it records nothing by itself. There, the order is recorded by Shopify’s checkout code in the visitor’s browser when they accepted, and the webhook’s copy of it is dropped.
A refusal wins. If Trace holds a refusal for the visitor, the order is not recorded, whatever your server says.
On /v1/event, Trace uses the consent your server states, except that a refusal Trace already holds for the visitor always wins. Send GRANTED only for a visitor who allowed analytics.
Codes are the exception. An order that carries a discount code is added to Codes whatever the visitor’s consent, as your own record of the order, with nothing that names a visitor.

Refunds

Your server sends a refund as the order id and what the order is worth now, not the amount refunded. Trace only ever lowers a value, so a repeat of the same refund, or a late one that carries an older and higher figure, changes nothing.

The value drops on the journey and in every report built from it. The channels keep the same share of the order, so each channel’s revenue falls in proportion.
Codes shows the lower value too.
An order still held in the 60 minute wait is lowered there, so it is counted at the lower value if it is released.
An order that has already been counted in the anonymous totals is not changed.
A refund names no visitor and adds nothing, so consent does not gate it. The reply says whether Trace found the order.

The Shopify app sends refunds. The WooCommerce plugin does not send them today, so a WooCommerce refund does not change the value in Trace unless your own code calls the refund route.

What it gives you, and what it does not

An order is recorded at its real value from your own order system, also when the visitor never reaches the thank you page, for a visitor who allowed analytics.
Refunds lower the value, where your shop or server sends them.
An order is counted once, however many routes report it.
Consent still applies, as it does to the tag, and nothing identifying a person is sent.

It does not make a visit visible that the tag never saw. With no visitor key an order cannot join a journey, and on a UK or EU site it is not recorded at all. How is conversion value calculated? explains where the value comes from.

Sending an order from your own server

Copy your site’s tracking key from its install page in Trace.
On your checkout page, read the visitor key and the request id the tag stored, and send them to your server with the order. If the tag stored none, send the order without them.
From your server, send POST https://app.usetrace.io/api-proxy/v1/event/purchase with the header x-trace-api-key set to the key, and a JSON body holding order_id and value. Add currency, timestamp, anon_user_key for the visitor key and request_id for the request id when you have them.
Read the reply. Trace answers 202 even when it holds an order back or ignores it, and says which in the body: buffered means it is waiting for the visitor’s answer.
Check the order under Journeys, or in the event stream with debug mode on. Enable debug mode and read event stream shows how.

For a refund, send POST /v1/event/refund with order_id and value. Conversion detection methods: URL, DOM, JS, server explains when to choose a server conversion.

How it relates to the conversion feed

They are different things that can work together. Server side tracking is your server telling Trace about an order. The conversion feed is Trace telling your ad platform about a conversion its own tag missed, in a daily batch, from Trace’s server to the platform’s.

A server order reaches the conversion feed only if it joined a journey that holds a paid click, so an order with no visitor key cannot be sent. How the conversion feed works shows the path, and the conversion feed in detail has the rules.