Subscription Status Codes

Each subscription in the CMS is assigned a computed status code that reflects the current state of that subscription. Status codes are calculated in real time from the subscription’s status flag, nextRenewal date, cancellationRequestDate, cancellationReason, and any in-flight grace period payments.

The status code (integer) and its human-readable label are exposed:

In the Customers list via the Subscription status column (grouped by subscription group, showing the most recent subscription per group).
As a filter in the Customers list via the same Subscription status filter.
In the Subscriptions list via the Status column on a per-subscription basis.
In the Subscription API as status_code (integer) and status_code_text (string) on every subscription object.

Status Code Reference

Code	Label	Description
1	Active	The subscription is paid and current. `nextRenewal` is in the future and `status = 1`.
2	Active (grace period)	The renewal date has passed but an automated payment charge is still in flight (`pending_charge`). The subscriber retains full access during this window (up to 10 days).
3	On hold (retrying)	The renewal date has passed, no grace-period payment was found, but `status` is still `1` — the billing engine is actively retrying. Access is typically restricted depending on your configuration.
4	Pending user cancellation	The subscriber has submitted a cancellation request but still has access until the end of the current paid period (`nextRenewal` is in the future, `status = 0`).
5	User cancelled	The subscriber voluntarily cancelled and the paid period has ended (`nextRenewal` is in the past, `status = 0`, cancellation request was recorded).
6	On hold	The subscription has lapsed (`nextRenewal` is in the past, `status = 0`) with no cancellation request and no upgrade — typically involuntary churn where all retry attempts have been exhausted.
7	Pending involuntary cancellation	The subscription record exists with `status = 0` and a future `nextRenewal` but no cancellation request. Usually indicates a subscription that has been stopped involuntary by an admin or automated process.
8	Not started	The subscription has `status = 0` and no `nextRenewal` date at all — it has never been activated. Not commonly encountered unless there is a data error.
9	Upgraded	The subscription was cancelled because the subscriber moved to a any other pricing tier (`cancellationReason = 'Upgraded'`). The upgraded subscription will appear separately with its own status.

How the Code Is Computed

The logic follows a strict evaluation order:

status = 0 AND nextRenewal is NULL  →  8 (Not started)
status = 1 AND nextRenewal > now    →  1 (Active)
status = 1 AND nextRenewal ≤ now
    AND within 10-day grace window
    AND pending_charge payment found →  2 (Active – grace period)
status = 1 AND nextRenewal ≤ now   →  3 (On hold – retrying)
status = 0 AND cancellationReason = 'Upgraded'  →  9 (Upgraded)
status = 0 AND nextRenewal > now
    AND cancellationRequestDate set →  4 (Pending user cancellation)
status = 0 AND nextRenewal > now   →  7 (Pending involuntary cancellation)
status = 0 AND nextRenewal ≤ now
    AND cancellationRequestDate set →  5 (User cancelled)
status = 0 AND nextRenewal ≤ now   →  6 (On hold)

Filtering Customers by Subscription Status

On the Customers list page, use the Subscription status filter to narrow the list to customers whose active subscription (per group) matches a specific status code.

The filter operates on the most recent subscription per subscription group for each customer.
If a customer has subscriptions in multiple groups (e.g. Digital and Print), they will appear in the results if any of their group-latest subscriptions match the selected status.
The filter accepts one or more status codes. For example, selecting On hold (retrying) (code 3) and Active (grace period) (code 2) together returns all customers who have at least one subscription currently in a billing retry or grace state — useful for targeting dunning communications.

Common filter use cases

Goal	Status codes to select
All paying subscribers	1, 2
Subscribers at risk of churning	2, 3
Subscribers who have churned (involuntary)	6
Subscribers who cancelled themselves	5
Subscribers mid-cancellation (still have access)	4
Invalid subscriber state	8
Upgraded subscribers	9

API

Every subscription object returned by the API includes:

{
  "status_code": 3,
  "status_code_text": "On hold (retrying)"
}

You can use these fields to drive downstream logic in integrations, automations, or analytics exports without re-implementing the status logic yourself.

Checking Customer Eligibility

When a frontend or an external system (e.g. a paywall, a third-party integration, or a membership benefit platform) needs to decide whether a customer is currently an eligible subscriber, it should evaluate status_code against the following rule:

A customer is eligible if they have at least one subscription with status_code of 1 (Active) or 2 (Active – grace period).

Code 2 must be treated as eligible because the subscriber has paid for the current period and a charge is in transit — denying access is not preferred.