Track conversions

Routing learns from the conversions your code reports. 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

routingcat.identify(event, accountId) links the request’s 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.
routingcat.track(event, name, options) reports an event, such as signup or purchase.

Both run in your server code, the files under server/ that Nitro runs, where RoutingCat’s module makes routingcat available with no import. Each takes first the event your handler receives; a call without it sends nothing on the server, and says so in your server’s logs. They read the visitor from the request’s rc_vid cookie, send with the credential your build gives your server, so no key goes in your code, and never throw. They send within the request’s lifetime, and never delay the response. await routingcat.identify(…), as the examples write it, and call routingcat.track(…) without await: awaiting it waits only until its event is handed off, never for the send. RoutingCat joins a link and the events in whichever order they arrive.

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 Nuxt app’s server code: its API and server routes	`routingcat.track` and `routingcat.identify`, with the handler’s `event`.
Your pages, in the browser	`routingcat.track`, `routingcat.identify` and `routingcat.link`, imported from `routingcat/vue` in your components, without an `event`. They post through your site’s `/_rc` path, with your site’s public key, which your build gives your pages.
Another backend, or a webhook	The HTTP events API, with the server events key, or a server route of your Nuxt app that the webhook reaches.

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 Stripe’s event.id, or signup:<account id>. A server track without one is logged once and dropped. Browser 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 occurredAt, a Date, an RFC 3339 string or a number of Unix seconds, and one more than five minutes ahead is rejected. Without it, the event takes the time of the call. 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.ts 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. Your server’s calls send server events, and your pages’ calls browser events. 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, unitValue }, unit_value over HTTP, at most 200. Revenue is reported; routing learns from the objective alone.
Environments: in development, the calls record nothing and log each call. A build that registered nothing records nothing either, and your server’s calls log each call. Events from a preview deployment, or sent with the preview server key, stay out of results, which count production only, so testing never shows in them.

Record a conversion in your server code

Where your server creates the account, call await routingcat.identify(event, user.id), then routingcat.track(event, 'signup', { id: `signup:${user.id}` }). Identify again where your server first reads the signed-in user, at every sign-in. When a provider such as Clerk creates the account, Clerk and other auth providers shows where.

A conversion with no account, such as joining a waitlist, tracks alone. The example app’s waitlist route, which a sign-up form posts to at /api/waitlist, derives its id from a hash of the address, so the same address joining twice counts once, and the address is never kept:

// The waitlist's server route, which a sign-up form posts its address to: it checks the address and
// keeps nothing, then tracks the conversion with `routingcat.track(event, …)`, the server's
// `routingcat`, which routingcat/nuxt makes available in the server's code, deduplicated per address
// without keeping it, by a hash of it. The call sends within the request's lifetime, never delaying
// the response, and never throws, so it is not awaited.
const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/

export default defineEventHandler(async (event) => {
  const body = await readBody<{ email?: unknown } | null>(event)
  const email = String(body?.email ?? '').trim()
  if (!EMAIL.test(email)) {
    setResponseStatus(event, 400)
    return { ok: false, message: 'Enter a valid email address.' }
  }
  const digest = await crypto.subtle.digest(
    'SHA-256',
    new TextEncoder().encode(email.toLowerCase()),
  )
  const id = Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')
  routingcat.track(event, 'waitlist', { id: `waitlist:${id}` })
  return { ok: true, message: 'You are on the list.' }
})

The visitor is the one whose browser posted the form, read from the request’s cookie; the route names none.

Record it from an app on a subdomain

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

Record it from another backend

At sign-up, the backend 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"}]

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 that backend: it writes events for your site. Access and keys says how to replace it.

Record it on another registrable domain

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

On lumen.so, routingcat.link(url) from routingcat/vue, in a component, adds the visitor id to a link that crosses. Call it once the component is mounted, or in the link’s click handler: in the server’s render it returns the link unchanged.
On lumen.app, load the browser entry with data-collector set to https://lumen.so, so that it posts through that site’s /_rc path. It adopts the id, removes it from the address bar, and uses it for identify and 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.

Record a form with no backend

For a form your code never sees, such as a third-party waitlist form, your page tracks on submit, in a component, with routingcat from routingcat/vue and without an event. 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').

Alternatively, make the conversion a server event. Put the rc_vid cookie’s value in a hidden field, which your page’s code can read, and have the form’s webhook reach a server route of yours. The route tracks the conversion with the submission’s own id as its id, and visitorId set to that field’s value: the webhook’s request carries no visitor cookie of its own.

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.
A server call that sends nothing says why in your server’s logs, on a line starting routingcat:: a call without its event, a track without an id, a build that registered nothing, or a request RoutingCat’s module didn’t see.

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.	From a request with no visitor cookie, such as a webhook’s, pass `visitorId`, or `accountId` (conversions with no key).
unlinked	Its account id was never linked to a visitor.	Call `routingcat.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 routingcat.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.ts`, 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.