Entrar
.md

Ciclo de Vida do Cliente

Todo cliente do Guper carrega um estágio de ciclo de vida que reflete o momento do relacionamento dele com a marca. O estágio é atribuído automaticamente pela plataforma (você não precisa gerenciá-lo) e vem no JSON do cliente como uma tag.

São três estágios, e o cliente tem exatamente um ativo por vez:

Estágio tag O que significa
🔵 Lead 5 Cadastro criado, mas ainda não comprou. Um contato/potencial.
🟢 Customer 6 Já fez pelo menos uma compra e está ativo.
🔴 Churn 7 Era cliente mas ficou inativo (parou de comprar além do esperado).

Quando cada tag é atribuída

Este é o ponto central — o momento exato em que o cliente entra em cada estágio:

Momento na jornada Tag resultante
O cadastro é criado (primeiro contato, ainda sem pedido) recebe Lead
O cliente faz a primeira compra (primeiro pedido processado) perde Lead, recebe Customer
O cliente fica inativo — passa a janela esperada de recompra sem comprar perde Customer, recebe Churn
Um cliente em Churn compra de novo perde Churn, volta a Customer (reativação)
  cadastro                 1ª compra                  inatividade
 ──────────▶  🔵 Lead  ───────────────▶  🟢 Customer ───────────────▶  🔴 Churn
                                              ▲                             │
                                              └───────── nova compra ───────┘
                                                       (reativação)

Depois da primeira compra, o cliente nunca volta a ser Lead — ele alterna apenas entre Customer e Churn.

Quanto tempo até virar Churn?

A janela de inatividade não é fixa — ela se adapta ao ritmo de compra de cada cliente:

  • Quem compra com frequência vira Churn mais cedo.
  • Quem compra espaçado tem uma janela bem mais longa.

Na prática:

  • Cliente com histórico (2+ compras): vira Churn após ~3× o próprio intervalo médio de recompra. Ex.: quem costuma comprar a cada ~15 dias vira Churn em ~45 dias.
  • Cliente de primeira compra (ainda sem cadência própria): usa o intervalo médio típico da loja como janela (~1×). Ex.: se a loja recompra em média a cada ~80 dias, o comprador de primeira viagem tem ~80 dias.

Como ler no JSON do cliente

O estágio vem dentro do array tags da resposta de Buscar cliente, junto das demais tags. Basta procurar a tag cujo tag seja 5, 6 ou 7:

{
    "id": 4224868,
    "name": "Ivone Suerez",
    "tags": [
        {
            "tag": 6,
            "name": "Customer",
            "createdAt": "2026-05-28T20:20:26-03:00"
        },
        {
            "tag": 2,
            "name": "Opt-in",
            "createdAt": "2026-05-28T20:18:34-03:00"
        }
    ]
}
  • Identifique o estágio pelo tag (5/6/7) ou pelo name (Lead/Customer/Churn).
  • Só uma tag de ciclo de vida aparece por vez — a do estágio atual.
  • Se nenhuma das três aparecer, o cliente ainda não foi classificado (ex.: cadastro muito recente sendo processado).

O objeto lifecycle (recomendado)

Além da tag, a resposta traz um objeto lifecycle dedicado — a forma mais direta de ler o estágio e, principalmente, a previsão de churn:

"lifecycle": {
    "stage": "customer",                     // lead | customer | churn
    "churnAt": "2026-08-25T20:20:26-03:00",  // (customer) quando vira churn se não comprar
    "churnedAt": null                        // (churn) quando ficou inativo
}
  • stage — o estágio atual (lead / customer / churn).
  • churnAt — presente só quando customer: a data prevista de churn. É um forecast vivo — cada nova compra empurra essa data pra frente.
  • churnedAt — presente só quando churn: quando o cliente entrou em churn.

Usando em campanhas

Como o estágio é uma tag, ele pode ser usado direto como segmento de campanha e de audiência:

  • Mirar Lead → campanhas de ativação (converter o contato na primeira compra).
  • Mirar Churn → campanhas de reativação (trazer o cliente de volta).
  • Mirar Customer → campanhas para a base ativa.