---
title: 'Customer Lifecycle'
description: 'How a customer moves through Lead → Customer → Churn, when each stage is assigned, and how to read it from the customer JSON.'
---

# Customer Lifecycle

Every Guper customer carries a **lifecycle stage** that reflects where they are in their relationship with the brand. The stage is **assigned automatically** by the platform (you don't manage it) and comes back in the customer JSON as a **tag**.

There are three stages, and a customer has **exactly one** active at a time:

| Stage | `tag` | What it means |
|-------|:-----:|---------------|
| 🔵 **Lead** | `5` | Registered, but **hasn't purchased yet**. A contact/prospect. |
| 🟢 **Customer** | `6` | Has made **at least one purchase** and is **active**. |
| 🔴 **Churn** | `7` | Was a customer but **went inactive** (stopped buying beyond the expected window). |

## When each tag is assigned

This is the key part — **the exact moment** a customer enters each stage:

| Moment in the journey | Resulting tag |
|-----------------------|---------------|
| The **record is created** (first contact, no order yet) | gets **Lead** |
| The customer makes their **first purchase** (first order processed) | loses Lead, gets **Customer** |
| The customer **goes inactive** — passes the expected repurchase window without buying | loses Customer, gets **Churn** |
| A churned customer **buys again** | loses Churn, back to **Customer** (reactivation) |

```
  record                  1st purchase              inactivity
 ─────────▶  🔵 Lead  ──────────────▶  🟢 Customer ──────────────▶  🔴 Churn
                                            ▲                            │
                                            └───────── new purchase ─────┘
                                                     (reactivation)
```

> **After the first purchase a customer never becomes a Lead again** — they only alternate between **Customer** and **Churn**.

### How long until Churn?

The inactivity window is **not fixed** — it **adapts to each customer's buying rhythm**:

- Frequent buyers turn to Churn **sooner**.
- Infrequent buyers get a **much longer** window.

In practice:

- **Customer with history** (2+ purchases): turns to Churn after ~**3× their own average repurchase interval**. E.g., someone who usually buys every ~15 days churns in ~45 days.
- **First-purchase customer** (no own cadence yet): uses the **store's typical repurchase interval** as the window (~1×). E.g., if the store repurchases every ~80 days on average, a first-time buyer gets ~80 days.

## How to read it in the customer JSON

The stage comes inside the **`tags`** array of the [Get customer](/en-US/api-reference/register/customer/get) response, alongside the other tags. Just look for the tag whose `tag` is `5`, `6`, or `7`:

```json
{
    "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"
        }
    ]
}
```

- Identify the stage by the **`tag`** (`5`/`6`/`7`) or the **`name`** (`Lead`/`Customer`/`Churn`).
- **Only one** lifecycle tag appears at a time — the current stage.
- If **none** of the three appears, the customer hasn't been classified yet (e.g., a very recent record still being processed).

### The `lifecycle` object (recommended)

Besides the tag, the response carries a dedicated **`lifecycle`** object — the most direct way to read the stage and, above all, the **churn forecast**:

```json
"lifecycle": {
    "stage": "customer",                     // lead | customer | churn
    "churnAt": "2026-08-25T20:20:26-03:00",  // (customer) when they turn to churn if they don't buy
    "churnedAt": null                        // (churn) when they became inactive
}
```

- `stage` — the current stage (`lead` / `customer` / `churn`).
- `churnAt` — present **only when `customer`**: the predicted churn date. It's a **live forecast** — every new purchase pushes it forward.
- `churnedAt` — present only when `churn`: when the customer became inactive.

## Using it in campaigns

Because the stage is a tag, it can be used directly as a **segment** in campaigns and audiences:

- Target **Lead** → **activation** campaigns (convert the contact into a first purchase).
- Target **Churn** → **reactivation** campaigns (win the customer back).
- Target **Customer** → campaigns for the active base.
