Commerce Lifecycle States

Lifecycle states are the current snapshot of each commerce's retention state, computed by the Reten engine. Each state answers the question: "where in the retention cycle is this commerce, under which configuration, and since when?".

This section documents the read and write contract for those states.

Capabilities

The API exposes five capabilities over the commerce-lifecycle-snapshots resource:

Authentication

Every lifecycle state endpoint accepts two authentication methods:

Required permissions:

The resource: state snapshot

A lifecycle state (snapshot) is represented with this canonical shape. The surfaces that return the "raw" resource (list, batch lookup, upsert) use exactly these fields:

{
  "id": "5d000000-0000-4000-8000-000000000001",
  "commerce_id": "c0000000-0000-4000-8000-000000000001",
  "external_id": "SV-001",
  "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "code": "AT_RISK_MONTHLY",
  "label": "At risk (monthly)",
  "stage": "ENGAGEMENT",
  "last_computed_at": "2026-06-10T06:00:00.000Z",
  "state_changed_at": "2026-05-22T06:00:00.000Z"
}

Identifier model (dual)

A commerce can be referenced in two equivalent ways across the entire states API:

• Reten UUID (commerce_id) — the internal identifier, e.g. c0000000-0000-4000-8000-000000000001.
• External code (external_id) — the commerce's code in your own system, e.g. "SV-001".

Each endpoint declares which one(s) it accepts:

Lifecycle stages (stage)

The stage field takes one of three possible values:

• ACTIVATION
• ENGAGEMENT
• RESURRECTION

The (stage, code) pair defines a commerce's visible state.

Freshness: last_computed_at vs state_changed_at

These are two timestamps with distinct semantics; understanding the difference is key to consuming this data correctly.

state_changed_at rules:

• On create, it is initialized equal to last_computed_at.
• On update, it only changes if the (stage, code) pair differs from the one that already existed. If only the label or the last_computed_at changes but (stage, code) stays the same, state_changed_at does not move.

Example of the evolution of a single commerce:

Behavior with unresolved or stale data

Unresolved

An identifier is unresolved when no snapshot exists for it. The API groups two cases together (intentionally — the result is unobtainable either way):

• The commerce does not exist in the tenant.
• The commerce exists but does not yet have a computed state.

How it manifests per endpoint:

Stale (old data)

The API does not flag freshness or delete old states: a snapshot lives until the engine overwrites it. "Freshness" is decided by the consumer, comparing last_computed_at against the current moment and applying its own threshold (e.g. "I consider anything computed more than 24h ago stale").

To find recent states without walking everything, list accepts the state_changed_since filter, which returns only states whose state_changed_at is after a given date.

AGC identifier and setup flow

The lifecycle state is per (commerce, AGC) pair, not unique per commerce. An "Activity Generation Config" (AGC) is the configuration under which the engine computes states; the same commerce can have a different state under each AGC.

That's why the activity_generation_config_id parameter appears in every endpoint — read and write:

• It is optional on reads. If you omit it, you get the states across all AGCs of the commerce/tenant.
• It matters if you want to avoid "mixing" data. Filtering by a specific AGC ensures you read only the states computed under that configuration, without intermingling results from other AGCs.
• It is required on writes (single and batch upsert), because a state is always written under a specific AGC.

How to obtain the available AGC IDs

If you want to filter by AGC, first discover the ones that exist in your tenant with:

GET /api/activity-generation-configs

Auth: requires the activity-generation-config:view permission. Responds with an array; take the id of the AGC you care about and use it as activity_generation_config_id:

[
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000001",
    "name": "B2B Retention",
    "description": "Retention cycle for wholesale customers"
  },
  {
    "id": "a1b2c3d4-0000-4000-8000-000000000002",
    "name": "Q1 Resurrection",
    "description": "First-quarter win-back campaign"
  }
]