Step 9 — Define conversions
Turn the events Atribu is already storing into the conversions it counts — the step that decides what your ROAS is made of.
By now Atribu is receiving outcome events: leads and appointments from your CRM, payments from Stripe or MercadoPago, whatever your own systems post. It is storing all of them and counting only the ones a conversion definition claims.
One definition is required before anything works
At least one definition that is both revenue_type: "cash" and
attribution_eligible — otherwise nothing this profile records can ever
produce a ROAS. That is readiness's conversion_definitions_valid step, and
until it is done the dashboard shows conversions with no revenue behind them.
The three fields
| field | what it decides |
|---|---|
| source events | which raw event_type values this definition claims — unique across the profile |
| revenue type | cash | pipeline | gross. Only cash counts toward ROAS. |
| attribution eligible | whether this conversion may be credited to a touch at all |
pipeline is a CRM's projected deal value; gross is an order before
refunds. Both are tracked and neither is revenue. Mixing them into one number
is the single fastest way to make every ratio on the dashboard meaningless —
see Revenue types.
Go to Settings → Outcomes
Every new profile is seeded with sensible defaults — Payment Received (cash),
Lead Created, Appointment Booked, Closed Won, Order Placed. Check that the one
representing money arriving is cash.
Look at what is arriving and unclaimed
The suggestions list shows every event type Atribu has seen that no definition
names, with how often it fires and what it is worth. That is where a missing
checkout_completed shows up.
Add or edit a definition
Name it, pick its source events, set the revenue type and whether it is attribution-eligible. Saving replays the profile, so past periods update too.
Set the attribution windows
Settings → Attribution. Click 30 days, view-through 24 hours, first-touch
90 days are the defaults, and defaults are a legitimate answer. Set
cash_window_days only if your sales close long after the click.
Full walkthrough: Conversion goals and Attribution windows.
Suggestions first — never invent an event name.
curl -H "Authorization: Bearer atb_live_YOUR_KEY" \
"https://api.atribu.app/api/v1/goals/definitions/suggestions"Each row carries suggested_revenue_type, suggested_display_name,
suggested_attribution_eligible and suggested_meta_event_name — pre-filled
form fields, not classifications. Show them to your human, or say plainly
that you accepted them.
curl -sX POST https://api.atribu.app/api/v1/goals/definitions/preview \
-H "Authorization: Bearer atb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"source_event_names":["payment_received"],"revenue_type":"cash"}'curl -sX POST https://api.atribu.app/api/v1/goals/definitions \
-H "Authorization: Bearer atb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"conversion_key": "payment_received",
"display_name": "Payment received",
"source_event_names": ["payment_received"],
"revenue_type": "cash",
"attribution_eligible": true
}'Scope: goals:write. A 409 names the definition that already claims one
of your source events — two definitions over one event would double-count it in
every report.
curl -sX PATCH https://api.atribu.app/api/v1/profile/attribution-settings \
-H "Authorization: Bearer atb_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"click_window_days": 30}'Both writes queue a full-profile replay
A definition change re-derives conversions from stored outcome events; a window
change redefines which touches attach to which conversion. Past periods
change. That is why preview and diff exist — call them first.
Over MCP
list_outcome_events, suggest_conversion_definitions,
create_conversion_definition and set_attribution_windows are the same four
calls as tools (#1058). The two writes take mode: "preview" — which costs
nothing and returns what would be captured — before mode: "confirm".