Batch Lookup

Resolve up to 100 commerce identifiers to their lifecycle states in a single call, with partial results.

POST /api/commerce-lifecycle-snapshots/batch-lookup

Resolves a closed set of identifiers (up to 100) to their lifecycle states in a single operation. Unlike the list, it is not paginated: you provide the exact set to query.

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

Partial results. The request never fails wholesale because of identifiers that don't exist or that don't yet have a computed state: the resolved ones arrive in data and the rest are explicitly reported in unresolved.

Request Body

Field	Type	Required	Description
`commerce_ids`	UUID[]	One of the two	List of commerce UUIDs (max 100).
`external_ids`	string[]	One of the two	List of external codes (max 100).
`activity_generation_config_id`	UUID	No	If provided, returns only states from that AGC. If omitted, returns states across all AGCs of the requested commerces.

You must send exactly one of commerce_ids or external_ids — not both, not neither. Sending both (or neither) responds 400. Identifier types cannot be mixed in a single request.

Example

curl -X POST "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ids": ["SV-001", "SV-002", "SV-099"],
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001"
  }'

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      external_ids: ["SV-001", "SV-002", "SV-099"],
      activity_generation_config_id: "a1b2c3d4-0000-4000-8000-000000000001",
    }),
  },
);
const result = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots/batch-lookup",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "external_ids": ["SV-001", "SV-002", "SV-099"],
        "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
    },
)
result = response.json()

Response `200 OK`

{
  "data": [
    {
      "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-06-08T06:00:00.000Z"
    },
    {
      "id": "5d000000-0000-4000-8000-000000000002",
      "commerce_id": "c0000000-0000-4000-8000-000000000002",
      "external_id": "SV-002",
      "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
      "code": "HEALTHY",
      "label": "Healthy",
      "stage": "ENGAGEMENT",
      "last_computed_at": "2026-06-10T06:00:00.000Z",
      "state_changed_at": "2026-06-03T06:00:00.000Z"
    }
  ],
  "unresolved": ["SV-099"]
}

Field	Type	Description
`data`	snapshot[]	Resolved states, in the shape of the snapshot resource (raw resource, without nested relations).
`unresolved`	string[]	Identifiers from the request that could not be resolved. Includes both nonexistent commerces and commerces with no computed state — the API does not distinguish them.

Errors

Status	Description
`400`	Both identifiers or neither were sent; more than 100 elements; or an invalid UUID in `commerce_ids`.
`401`	Missing or invalid API key.
`403`	The credential lacks the `commerce-lifecycle-snapshot:view` permission.