Upsert Individual

POST /api/commerce-lifecycle-snapshots

Cria ou atualiza (upsert) o estado de ciclo de vida de um comércio sob uma AGC específica. Se já existe um estado para o par (commerce, AGC), é atualizado; senão, é criado. Retorna o estado resultante.

Auth: Obrigatório — permissão commerce-lifecycle-snapshot:create

Para gravar muitos estados de uma vez, use o upsert por lote (até 1000 items em uma única operação). Este endpoint grava um e só aceita commerce_id (UUID), não um código externo.

Corpo da Requisição

Campo	Tipo	Obrigatório	Descrição
`commerce_id`	UUID	Sim	UUID do comércio na Reten. Deve existir.
`activity_generation_config_id`	UUID	Sim	AGC sob a qual o estado é gravado. Veja identificador de AGC.
`code`	string	Sim	Código do estado de retenção (1–255 caracteres). Deve corresponder a um `UserRetentionStatusConfig` do tenant; um código desconhecido responde `400`.
`stage`	enum	Sim	Estágio: `ACTIVATION`, `ENGAGEMENT` ou `RESURRECTION`.
`last_computed_at`	ISO 8601	Sim	Quando o motor calculou este estado.

O label não é enviado: a Reten o deriva do code com base na config de estados de retenção (fonte da verdade do par code → label). O state_changed_at também não é enviado: a Reten o gerencia — só avança se o par (stage, code) mudar. Veja frescor.

Exemplo

curl -X POST "https://api.reten.ai/api/commerce-lifecycle-snapshots" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "commerce_id": "c0000000-0000-4000-8000-000000000004",
    "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
    "code": "ONBOARDING",
    "stage": "ACTIVATION",
    "last_computed_at": "2026-06-10T06:00:00.000Z"
  }'

const response = await fetch(
  "https://api.reten.ai/api/commerce-lifecycle-snapshots",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      commerce_id: "c0000000-0000-4000-8000-000000000004",
      activity_generation_config_id: "a1b2c3d4-0000-4000-8000-000000000001",
      code: "ONBOARDING",
      stage: "ACTIVATION",
      last_computed_at: "2026-06-10T06:00:00.000Z",
    }),
  },
);
const snapshot = await response.json();

import requests

response = requests.post(
    "https://api.reten.ai/api/commerce-lifecycle-snapshots",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "commerce_id": "c0000000-0000-4000-8000-000000000004",
        "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
        "code": "ONBOARDING",
        "stage": "ACTIVATION",
        "last_computed_at": "2026-06-10T06:00:00.000Z",
    },
)
snapshot = response.json()

Resposta `201 Created`

Tanto ao criar quanto ao atualizar, o endpoint retorna o recurso snapshot resultante:

{
  "id": "5d000000-0000-4000-8000-000000000004",
  "commerce_id": "c0000000-0000-4000-8000-000000000004",
  "external_id": "SV-004",
  "activity_generation_config_id": "a1b2c3d4-0000-4000-8000-000000000001",
  "code": "ONBOARDING",
  "label": "Onboarding",
  "stage": "ACTIVATION",
  "last_computed_at": "2026-06-10T06:00:00.000Z",
  "state_changed_at": "2026-06-10T06:00:00.000Z"
}

Erros

Status	Descrição
`400`	Corpo inválido, `code` desconhecido, ou `stage` inválido.
`404`	O comércio (`commerce_id`) não existe.
`401`	Chave de API ausente ou inválida.
`403`	A credencial não tem a permissão `commerce-lifecycle-snapshot:create`.