Identify behavioral churn-risk signals

Why this matters

Customers often reduce meaningful product activity before cancellation, but a behavioral difference is not automatically a prediction. Plan changes, seasonality, account size, contract timing, product changes, and support issues can all explain the same pattern.

Use this workflow to discover and quantify historical associations. Treat the result as a hypothesis to validate on a later holdout period, not as a label to act on immediately.

What you get

• Exact retained and canceled historical cohorts
• Pre-outcome behavior comparisons for predefined product-value events
• Sample sizes, effect sizes, segment differences, and missing evidence
• A reviewed validation plan before any customer-level use

Walk through it

GET /v1/projects/:project_id/signal-map
GET /v1/projects/:project_id/onboarding
# Require status: "verified"; use live event/property reads for the selected signals.
GET /v1/projects/:project_id/event-property-keys?events=subscription_canceled,subscription_renewed,product_value_completed

Then run a bounded owner-side aggregate query using the current OpenAPI schema:

Endpoint: POST /v1/projects/:project_id/analytics/query
Query plan:
  - select one exact historical cancellation/renewal outcome window
  - bind one equal pre-outcome behavior window per identity
  - exclude behavior after the outcome
  - aggregate predefined value-event counts by outcome and plan segment
  - return cohort sizes, distributions, and effect sizes; no raw identities

{
  "rows": [
    {
      "signal": "product_value_completed",
      "plan": "pro",
      "canceled_accounts": 84,
      "renewed_accounts": 391,
      "canceled_median": 2,
      "renewed_median": 11
    }
  ]
}

This supports a statement that the measured value event was less frequent in the canceled historical cohort. It does not prove that low activity causes churn or that every currently quiet account will cancel.

The output

Historical churn-signal review — <exact bounds>

Observed associations
- <signal>: <canceled distribution> vs <renewed distribution>
- sample: <cohort sizes and plan segments>

Limitations
- <confounding, sparse outcomes, missing identity, seasonality, instrumentation change>

Hypothesis
- <explicitly labelled risk hypothesis>

Validation before operational use
- freeze the rule
- test it on a later untouched cohort
- measure false positives and segment stability
- obtain CS/privacy review before inspecting customer-level matches

Do not produce a “31 users will churn” claim from this analysis. If a later validated rule is used to prepare a private review queue, a human must decide whether and how to contact any customer.

Setting it up

Record billing outcomes from the trusted server or billing webhook using AGENTRY_SERVER_API_KEY, with a stable account or user identifier and only the necessary plan context. Define one or more value events from the product’s real business logic and verify them with live traffic.

Avoid copying cancellation notes, message bodies, or sensitive payment details into analytics properties. Re-run validation after material product, instrumentation, pricing, or customer-mix changes.

Variations

• “Compare the association by plan without pooling enterprise and self-serve customers.”
• “Use a later historical period as a holdout for the frozen hypothesis.”
• “Identify which required signal is too sparse to support this analysis.”
• “Compare expansion outcomes instead of cancellation, with the same caveats.”