Track conversions

Routing learns from the conversions your code reports. On a site whose templates Vercel or Cloudflare serves, your server reports them through the HTTP events API, and a page with no backend through the browser entry’s script tag. This guide gives the two calls and their rules, a recipe for each place a conversion can happen, the checks that show conversions reaching their visits, and the tracking gap to record when tracking breaks. Auth providers and PostHog have guides of their own.

The two calls

Identify links the current visitor to an account: your app’s own id for a user. Send it when the account is created and at every sign-in, so that the person’s other devices link to it too.
Track reports an event, such as signup or purchase.

A conversion counts for a page when it reaches the visit that saw the page: through the visitor id it carries, or else through its account. An event with neither counts nowhere.

The visitor id is in the rc_vid cookie, which RoutingCat’s middleware or Worker sets on the pages it serves, for 400 days, on your registrable domain. So your server, and your other subdomains’ servers, read it from the requests they get. Behind a Worker in front of your server, a new visitor’s first request reaches your server without the cookie, which their next request carries.

Where the conversion happens	What to use
Your server, such as Laravel, Rails, Django, WordPress or PHP; another backend; a webhook	The HTTP events API, with the server events key, which `npx routingcat keys server` prints. The visitor id comes from the request’s `rc_vid` cookie.
A page with no backend of yours, such as a form a third party handles	The browser entry’s script tag, with your public key as `data-key`, which puts `routingcat.identify()` and `routingcat.track()` on the page’s `window.routingcat`. Each version’s URL and integrity hash are in the JavaScript API.

The rules

Account ids are stable and non-personal: your own record id, or the SHA-256 of the trimmed, lowercased email when there is no record. Never an email address. A person needs the same id on every device and at every sign-in, and RoutingCat has no use for their email.
Server events carry an id that names the conversion itself, such as signup:<account id>, or an order’s own id. Providers deliver some events twice, and RoutingCat keeps one event per name and id, so a retry never counts twice. Browser events get one generated.
Times: a server event keeps its occurred_at, RFC 3339 or a number of Unix seconds, and one more than five minutes ahead is refused. A browser event takes the time RoutingCat receives it. A webhook can arrive hours late, and its conversion still counts when it happened.
Names are 1 to 64 characters, with no control character, + or /, since + joins the events of an objective where any one counts and / marks a page’s own objective. An event under a name routingcat.config.json doesn’t declare is recorded, but not analyzed until declared.
Sources: each event is server, browser or posthog, and results show the objective’s source beside it. A browser can send anything, so an objective worth defending comes from your server.
Values: value with currency, an ISO 4217 code, is money in major units, 29.99 for $29.99, and revenue sums it per currency. Without currency it is a plain quantity, never revenue. Optional items list { id, quantity, unit_value }, at most 200. Revenue is reported; routing learns from the objective alone.
Environments: results count production only. Events sent with the preview server key, from npx routingcat keys server --env preview, stay out of them, so give your staging and development environments that key.

At sign-up, where your server creates the account, it reads the rc_vid cookie from its own request, then posts the identity link and the event with the server events key. Laravel decrypts every cookie it reads, and empties one it didn’t encrypt, as rc_vid, so npx routingcat init leaves rc_vid out of its cookie encryption: $middleware->encryptCookies(except: ['rc_vid']); in bootstrap/app.php’s withMiddleware, or before Laravel 11, 'rc_vid' in $except in app/Http/Middleware/EncryptCookies.php. Where it finds neither, or both, it prints the edit instead: make it, then run npx routingcat doctor, which reports the exception missing until one of them holds it.

POST https://ingest.routingcat.com/v1/events
Authorization: Bearer sk_…
Content-Type: application/json

[{"type":"identity_link","id":"idl:acct_42:v_8v_ztmJDpYzDKH7UxXwXPA","visitor_id":"v_8v_ztmJDpYzDKH7UxXwXPA","account_id":"acct_42"},
 {"name":"signup","id":"signup:acct_42","visitor_id":"v_8v_ztmJDpYzDKH7UxXwXPA","account_id":"acct_42"}]

At every sign-in, post an identity link again, with that request’s visitor id, so the person’s other devices link to the account.
Later events need only account_id, since the identity link already ties the account to the visitor.
Write each field as the API names it: visitor_id, never visitorId. An event with a field the API doesn’t take is refused, and the answer names the field meant; your own data goes in properties.
Post off the response’s path, from a background job or after the response is sent. The answer waits until the events are stored durably, which can take several hundred milliseconds.
Retry freely. A request holds at most 100 events, and the answer gives a result for each, so one bad event never blocks the others; a retried event counts once. The events API reference has the limits and the answers.
Keep the key a secret of your server, in its environment, never in a template: it writes events for your site. Access and keys says how to replace it.

A conversion with no account, such as joining a waitlist, tracks alone, with an id that keeps one per person, such as waitlist: and a hash of the address.

Record it from an app on a subdomain

The rc_vid cookie is set on your registrable domain, so an app on app.lumen.com already reads the visitor id of lumen.com, and its backend posts as above.

Record a form with no backend

For a form your code never sees, such as a third-party waitlist form, the browser links and tracks on submit. Load the browser entry’s script tag in the page, with your public key as data-key; then track on submit. Where your app has accounts of its own, track alone, routingcat.track('waitlist', { id: 'waitlist:<hash>' }), with the hex SHA-256 of the trimmed, lowercased email in the id, so each address counts once and your server’s identify keeps your own record ids. Where there are no accounts, link first: routingcat.identify() with that hash, then routingcat.track('waitlist'). The browser entry posts through your site’s /_rc path, which RoutingCat’s middleware or Worker forwards, so that ad blockers that block RoutingCat’s own domain don’t stop it.

Alternatively, put the rc_vid cookie’s value in a hidden field, and forward the form’s webhook to a backend that posts as above, which makes the conversion a server event.

Record it on another registrable domain

From lumen.com to lumen.app, the cookie can’t follow, so the link carries the visitor id:

On lumen.com, routingcat.link(url) from the browser entry adds the visitor id to a link that crosses.
On lumen.app, load the browser entry with data-collector set to https://lumen.com, so that it posts through that site’s /_rc path. It adopts the id, removes it from the address bar, and uses it for routingcat.identify() and routingcat.track() for 7 days. An rc_vid cookie there comes first.
The owner adds the domain once, npx routingcat domains add lumen.app, since RoutingCat accepts browser calls only from your site’s domains.

Check that conversions reach their visits

The first event. After the deploy, npx routingcat doctor shows the objective’s first event within a minute of it, with its source. Until one happens, the check waits, which is expected: the first real conversion passes it, a visitor’s or your own, and nothing else waits on it. Converting once yourself on your production site, as a visitor would, is the only end-to-end proof that a conversion reaches RoutingCat and joins its visit, so it is recommended, though where converting costs money, as an order does, you may prefer to skip it. That conversion is recorded as a real one.

How they joined. After the next counts refresh, npx routingcat status sums up the last 7 days on its tracking line:

tracking  signup 84 in 7 days · joined 52% (visitor 48%, account 5%) · no routed visit 36% · no key 5% · unlinked 1% · outside window 6%

Share	Means	Fix
joined, by visitor or account	The conversion reached a visit that saw a routed page, through its visitor id or its account.	Nothing.
no routed visit	Its visitor never saw a routed page.	Nothing: it counts once its visitors do.
no key	It carried neither a visitor nor an account id.	Send `visitor_id`, from the `rc_vid` cookie, or `account_id` (conversions with no key).
unlinked	Its account id was never linked to a visitor.	Send an identity link at sign-up and at every sign-in (accounts never linked).
outside window	It came after its visit’s window had closed.	Nothing; a longer window costs learning speed, as Conversions and visits explains.

status also names identify calls without a visitor id, by sending host, and doctor names events under an undeclared name and the preview server key used in production.

Alarms. The silence alarm fires when a page’s matured visits make zero conversions improbable, and the drop alarm when an objective’s daily count falls far below its recent days, often after a deploy that broke the call. Both are errors in status: fix the call, then record a tracking gap.

Record a tracking gap

A tracking gap marks an interval when an outcome’s events weren’t tracked, such as after a deploy that removed the call that sends them. Visits in that interval then count as unknown rather than as no conversion, so conversions that happened but went unrecorded don’t read as visits that failed to convert. Record one only when tracking actually broke. You record each gap yourself; the drop alarm suggests one.

Run npx routingcat gap <outcome> --from <time> [--to <time>] [--note <text>], as in npx routingcat gap signup --from 2026-10-10T08:00:00Z --to 2026-10-11T09:30:00Z:

Part	What it takes
`<outcome>`	The objective, or a declared outcome, by its name in `routingcat.config.json`, such as `signup`
`--from`	When tracking stopped. Required
`--to`	When it worked again. Leave it out while the gap is still open, then run the same command, with the same outcome and `--from`, adding `--to`, to close it
`--note`	Why, in at most 500 characters, quoted

A time is an instant, such as 2026-10-10T08:00:00Z, a day, such as 2026-10-10, for its start at midnight UTC, or now. The gap applies to production results, and like every command that writes, gap takes --dry-run to show what it would record.