Goals with a money value

If your goals are worth money — a lead that closes, a quote accepted, a booking taken — send what each one was worth and the dashboard reports it beside your traffic.

POST https://truestat.io/api/v1/goals
Authorization: Bearer <your API key>
Content-Type: application/json

{
  "name": "lead_won",
  "value_cents": 250000,
  "currency": "usd",
  "visitor_id": "<the ts_vid you stored>"
}

value_cents is in the currency's smallest unit, so 250000 is $2,500.00.

Why this one needs an API key

Your site key ships in every page's HTML. A figure the browser could send is a figure anyone reading your source could send, so no amount is accepted from the script or from the server route.

The key needs the goals:write scope. That is deliberately separate from reading: a key wired into a reporting dashboard should not be able to write your conversion numbers. Create one under Settings → API keys.

The two-event pattern

A lead and a closed deal are two different events, and measuring both is what makes the conversion rate real:

window.truestat("lead");                 // browser, immediately

POST /api/v1/goals                        // server, a week later
{ "name": "lead_won", "value_cents": 250000, "currency": "usd",
  "visitor_id": "<stored>" }

Someone who counts both is measuring the conversion rate. Someone who writes an estimated value onto the single first event is assuming it, and can never see that they were wrong.

Keeping the visitor id

Write the ts_vid cookie into your own database when you record the lead, and hand it back here when the deal closes. The cookie does not live long enough to still be there a week later — this is the same job subscription_data.metadata does in Stripe, for the same reason.

The fields

occurred_at is worth using when you post a deal that closed yesterday — without it the goal lands on today and your daily chart is wrong.

What comes back

{
  "data": {
    "name": "lead_won",
    "site_id": "…",
    "attributed": true
  }
}

A 202, and attributed tells you whether the goal was tied to a visit — false means no visitor_id was given, so the goal counts on the card but contributes to no breakdown.

When it does not work

A 402 is not a permission problem, so do not rotate the key when you see one.

Where it appears

The total sits on the Revenue tile, and each goal shows its own value beneath the name. Because goals filter the whole dashboard, clicking one narrows every other card to the people who converted — so "which campaign produced the leads that actually closed" is a question the panel answers.

You can also make these goals the site's revenue figure outright: see what counts as revenue.

Reserved names

subscription_started, subscription_renewed and the other names the billing integration writes are refused here. Sending one yourself would merge two sources into one row — the card would say "forty churns" with no way to tell which twenty came from where. See reserved names.