Conversion Definitions
The rules that turn raw outcome events into conversions — the step that decides what your ROAS is made of.
Atribu stores every outcome event a CRM, a payment provider, the tracker or your own systems send it. A conversion definition is what decides which of those events count, what their value means, and whether they may receive attribution credit at all.
This is the step where a profile stops producing numbers and starts producing the right numbers.
Two catalogs, one selector, and consumers get it wrong
GET /api/v1/goals/definitions returns both. conversion_definitions are
the actual conversion types, with revenue_type and attribution_eligible —
build a goal selector from these. outcome_definitions are CRM
pipeline-stage labels ("Descualificado"); they name the buckets outcome
counts are keyed by, carry no revenue or attribution semantics, and are not
goals.
The three fields that decide everything
| field | what it decides |
|---|---|
source_event_names | Which raw outcome_events.event_type values this definition claims. Unique across the profile — an overlap answers 409, because one event producing two conversions double-counts it in every report. |
revenue_type | cash | pipeline | gross. Only cash counts toward ROAS. A profile whose definitions are all pipeline records conversions that can never produce one. |
attribution_eligible | Whether this conversion may be credited to a touch at all. |
conversion_key is taken verbatim, never derived from display_name:
renaming a goal must not silently re-key every filter and saved report pointing
at it.
Suggestions first, then preview, then create
GET /api/v1/goals/definitions/suggestionsThe gap between what Atribu stores and what it counts: every
event_type seen in the window that no definition names. Each row carries how
often it fires, what it is worth, how many distinct people it reaches — and
pre-filled suggested_revenue_type, suggested_display_name,
suggested_attribution_eligible and suggested_meta_event_name. Those are
form fields, not classifications: an agent should show them to a human, or at
least say it accepted them.
It reads outcome_events, a durable table, so the window is not limited to
the 30-day ephemeral buffer.
POST /api/v1/goals/definitions/preview
POST /api/v1/goals/definitions/diffpreview answers "how many events, worth how much" for a candidate. diff
compares an existing definition against a proposed edit. Both are free of
consequence — call them before writing.
`revenue_sum` in a preview is not revenue
It is the raw event-value total for the matching events. Revenue is what the attribution pipeline produces after the definition exists.
POST /api/v1/goals/definitionsScope: goals:write. Creating or changing a definition stamps an audit row
and queues one full-profile replay — a definition change re-derives the
profile's conversions from its stored outcome events, so past periods change
too. That is the intended behaviour, and it is why diff exists.
The legacy route
POST /api/v1/goals still answers, and is deprecated. It carries a
Deprecation header, a Sunset date once one is set, and a
Link: …; rel="successor-version" pointing at
POST /api/v1/goals/definitions. Nothing is removed with less than 90 days'
notice — see the deprecation policy and the
API changelog.
| Method | Path | What it does |
|---|---|---|
GET | /api/v1/goals | List conversion goals |
POST | /api/v1/goals | Create a conversion goal |
DELETE | /api/v1/goals | Delete a conversion goal |
GET | /api/v1/goals/definitions | List the profile's outcome and conversion definitions |
POST | /api/v1/goals/definitions | Create one conversion definition |
PATCH | /api/v1/goals/definitions/{id} | Update one conversion definition |
DELETE | /api/v1/goals/definitions/{id} | Delete one conversion definition |
POST | /api/v1/goals/definitions/diff | Compare an existing conversion definition against a proposed edit |
POST | /api/v1/goals/definitions/preview | Preview what a candidate conversion definition would capture |
GET | /api/v1/goals/definitions/suggestions | List outcome events this profile receives but no conversion definition claims |
GET | /api/v1/goals/outcome-counts | Count the profile's outcome events in a window, by type |
PATCH | /api/v1/outcome-definitions/{id} | Update one outcome-definition's event key |
Generated from openapi.json. The full request and response schema for every operation is in the OpenAPI document.