Sign in
.md

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 response, alongside the other tags. Just look for the tag whose tag is 5, 6, or 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"
        }
    ]
}
  • 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:

"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.