Track conversions

Routing learns from the conversions your code reports. This guide gives the two calls and their rules, where to send each conversion from, 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. Call 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, from the rc_vid cookie, or else through its account. An event with neither counts nowhere.

Where the conversion happens	What to use
Your server: a sign-up, a payment, a form it receives, a webhook	The HTTP events API, with the server events key, and the visitor id from the request’s `rc_vid` cookie
The page, where your server never sees it: a third-party form, a click	`window.routingcat.track()` and `window.routingcat.identify()`, which RoutingCat’s head partial gives every page
Another backend, or an app on a subdomain	The HTTP events API, as from your server

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, and identify warns when an id holds @. 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: the provider’s event id, such as a payment’s, or signup:<account id>. The events API refuses an event without one. The page’s events get one generated. Providers deliver some events twice, and RoutingCat keeps one event per name and id, so a retry never counts twice.
Times: a server event keeps its occurred_at, RFC 3339 or Unix seconds, and one more than five minutes ahead is refused. An event from the page 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 } over HTTP, unitValue in the page, at most 200. Revenue is reported; routing learns from the objective alone.
Environments: on a host your config doesn’t list, as on your machine, the page’s calls record nothing and log to the console. Events from the preview environment, or sent with the preview server key, stay out of results, which count production only, so testing never shows in them.

Record a conversion from your server

At sign-up, your server reads the rc_vid cookie from its own request, then posts the identity link and the event with the server events key, which npx routingcat keys server prints:

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"}]

Read the cookie as the browser sent it. RoutingCat’s script writes rc_vid on your registrable domain, so your server receives it with each request after the visitor’s first page. 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, with the server helpers or without: $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.
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. 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: 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 derived from what makes it unique, such as a hash of the address, so the same address joining twice counts once.

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 receives the visitor id of www.lumen.com with each request, and its backend posts through the events API as above.

Record a conversion in the page

For a conversion your server never sees, such as a third-party waitlist form, the page tracks on submit. Where your app has accounts of its own, track alone, window.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: window.routingcat.identify() with that hash, then window.routingcat.track('waitlist').

window.routingcat is the object RoutingCat’s head partial gives every page that carries it. A call made before RoutingCat’s post part has loaded is kept, and sent once it has.
The calls never throw, so they never break a form, and they send the visitor id themselves.
They post straight to ingest.routingcat.com with your site’s public key, and RoutingCat accepts them only from your site’s domains: see Decide which domains send browser events.
A blocked script sends nothing, as an ad blocker can do: a conversion that matters is safer from your server.

Alternatively, put the rc_vid cookie’s value in a hidden field, and forward the form’s webhook to your server, which posts as above: the conversion is then a server event. The JavaScript API lists each call of window.routingcat.

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.	Identify 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 a track call. 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.