Look Up by Commerce

Get the lifecycle state (or states) of a single commerce, by UUID or external code.

GET /api/commerce-lifecycle-snapshots/:commerceIdentifier

Returns the lifecycle states of a single commerce, enriched with the commerce and AGC data. The path accepts a dual identifier: a Reten UUID or the commerce's external code, interchangeably.

Auth: Required — commerce-lifecycle-snapshot:view permission

Responds with an array, not an object. Without an AGC filter, the same commerce can have several states (one per AGC), which is why a list is always returned. With activity_generation_config_id, the array will have 1 element.

Path Parameter

Parameter	Type	Description
`:commerceIdentifier`	UUID \| string	UUID of the commerce in Reten (e.g. `c0000000-...`) or its external code (e.g. `SV-001`).

Query Parameters

Parameter	Type	Default	Description
`activity_generation_config_id`	UUID	-	If provided, returns only the state under that AGC. If omitted, returns the states across all AGCs of the commerce.

Example

# By external code
curl "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001" \
  -H "x-api-key: YOUR_API_KEY"

# By UUID, scoped to one AGC
curl "https://api.reten.ai/api/commerce-lifecycle-snapshots/c0000000-0000-4000-8000-000000000001?activity_generation_config_id=a1b2c3d4-0000-4000-8000-000000000001" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001",
  { headers: { "x-api-key": "YOUR_API_KEY" } },
);
const snapshots = await response.json();

import requests

response = requests.get(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots/SV-001",
    headers={"x-api-key": "YOUR_API_KEY"},
)
snapshots = response.json()

Response `200 OK`

Each element is the snapshot resource plus two nested objects: commerce and activity_generation_config.

[
  {
    "id": "5d000000-0000-4000-8000-000000000003",
    "commerce_id": "c0000000-0000-4000-8000-000000000003",
    "external_id": "SV-003",
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000002",
    "code": "WIN_BACK",
    "label": "Active win-back",
    "stage": "RESURRECTION",
    "last_computed_at": "2026-06-10T06:00:00.000Z",
    "state_changed_at": "2026-06-09T06:00:00.000Z",
    "commerce": {
      "id": "c0000000-0000-4000-8000-000000000003",
      "name": "Minimarket El Sol",
      "external_id": "SV-003"
    },
    "activity_generation_config": {
      "id": "a1b2c3d4-0000-4000-8000-000000000002",
      "name": "Q1 Resurrection",
      "description": "First-quarter win-back campaign"
    }
  }
]

Nested fields

Field	Type	Description
`commerce`	object \| null	`id`, `name` and `external_id` of the commerce.
`activity_generation_config`	object \| null	`id`, `name` and `description` of the AGC.

Errors

Status	Description
`404`	The commerce does not exist, or exists but has no computed state (with the AGC filter applied, if one was sent).
`401`	Missing or invalid API key.
`403`	The credential lacks the `commerce-lifecycle-snapshot:view` permission.

Unlike the batch lookup, here a commerce with no computed state responds 404 (not an empty body). If you need to distinguish "unresolved" without treating absence as an error, use the batch lookup.