Key Concepts: "Access", "Renewal", and "Final" Statuses
A subscription's status can reflect different things depending on where you view it:
-
Access state: Whether the user should currently have entitlement/access.
-
Renewal state: Whether the subscription is scheduled to renew at the next billing date.
-
Lifecycle/final state: Some statuses represent an end state and typically do not transition to another later (for example, a subscription that is Canceled remains canceled and does not later become Expired).
Turning auto-renew off generally does not remove access immediately. The subscriber remains entitled through the end of the current term, and the subscription will end at the term end unless renewed. A grace period (if configured) can allow access to continue after a payment failure while retries occur.
Dynamic Terms behave differently from Payment Terms in a few key ways. Dynamic Terms are always treated as auto-renewing — there is no auto-renew toggle available to end users. Instead of disabling auto-renew, users on Dynamic Terms perform a deferred cancellation, which allows access to continue until the end of the current billing period before the subscription expires. Payment Terms, by contrast, support a traditional auto-renew on/off toggle.
Status Definitions
Active
Meaning: The subscription is currently within a valid access period.
Common scenarios:
-
The subscription is in its current billed term and will attempt renewal at term end (unless auto-renew is off).
-
The subscription may still be Active even when auto-renew is disabled (Payment Terms only); access continues until the end of the term.
-
If the subscription is in a configured grace period after a failed payment, it can still be treated as active for access purposes.
Dynamic Terms note: A Dynamic Term subscription that has been upgraded to from a Payment Term will show as Active on the new subscription record. The subscription report currently only displays data for the current access period for Dynamic subscriptions.
Won't Renew
Meaning: The subscriber has access for the current term, but no future renewal is scheduled.
Typical causes:
-
Auto-renew is off for the upcoming renewal (Payment Terms).
-
An upgrade is scheduled (or an upgrade attempt failed), and the current term is effectively the last one.
-
Dynamic Terms: A deferred cancellation has been initiated — the user clicked "Cancel" in their account, which stops future renewal while keeping access active until the end of the current billing period. This is the Dynamic Terms equivalent of disabling auto-renew on a Payment Term.
-
Dynamic Terms: An upgrade to another dynamic term has been scheduled; the current subscription is set to end when the upgrade takes effect.
Payment Failed / Payment Failure
Meaning: A renewal payment attempt failed.
What happens next:
-
Piano may retry billing multiple times.
-
If a grace period is configured, the subscriber may retain access during that grace period while retries continue.
-
If payment is never successfully collected by the end of retries/grace period, the subscription typically transitions to a non-access state (for example, Expired or an equivalent webhook status).
Expired
Meaning: The subscription term has ended and was not renewed, so access is no longer granted.
Common causes:
-
Auto-renew was disabled and the current term reached its end date (Payment Terms).
-
A deferred cancellation on a Dynamic Term reached its end of billing period.
-
A fixed-length/manual subscription reached the end of its purchased period.
-
Payment retries failed and the subscription reached the end of the billing period plus any grace period without a successful renewal.
-
An external/administrative process marked the subscription as expired.
-
A Dynamic Term subscription had no further access periods configured, causing it to expire rather than renew.
If a subscription transitions between pricing phases (for example, intro rate → standard rate), that is not an expiration event. The subscription remains active until the overall term ends.
Canceled / Cancelled
Meaning: The subscription was manually terminated by the subscriber or an administrator.
Access impact:
-
Payment Terms — Cancellation of payment terms revokes access immediately (it is not just "turn off auto-renew"). Once canceled, the subscription remains in Canceled and does not later become Expired.
-
Dynamic Terms — "Cancel" (deferred): Selecting "Cancel" in account management on a Dynamic Term initiates a deferred cancellation. Access continues until the end of the current billing period, after which the subscription expires. The status shown is Won't Renew during this period, not Canceled.
-
Dynamic Terms — "Cancel Now" (immediate): Selecting "Cancel Now" as an administrator performs an immediate cancellation and revokes access immediately and sets the status to Canceled. This is equivalent to an immediate cancellation on a Payment Term.
|
Action |
Payment Terms result |
Dynamic Terms result |
|---|---|---|
|
Cancel (user-initiated) |
Access revoked immediately; status = Canceled |
Access continues to end of billing period; status = Won't Renew, then Expired |
|
Cancel Now (admin-initiated) |
Access revoked immediately; status = Canceled |
Access revoked immediately; status = Canceled |
|
Cancel Now and Refund (admin-initiated) |
Access revoked immediately; refund issued |
Access revoked immediately; refund issued |
Upgraded
Meaning: The subscription was replaced by another subscription/term (for example, Digital → Print + Digital, or Payment Term → Dynamic Term).
How it appears in logs:
-
The old subscription record is marked Upgraded.
-
A new subscription record is created for the new term/plan; reporting should typically focus on the most recent/current subscription for "active subscriber" counts.
Dynamic Terms note: When a subscription is upgraded to a Dynamic Term via Action Manager, the existing subscription status first changes to Won't Renew. On the next billing date, the existing subscription status transitions to Upgraded and a new Dynamic Term subscription is created with status Active. Note that it is not currently possible to upgrade from a Dynamic Term back to a Payment Term.
Auto-Renew vs. Subscription Status
In the Subscription Log report, you'll often see both a Subscription Status (for example, Active, Won't renew, Expired) and an Auto-renew field (boolean: TRUE / FALSE). These fields answer different questions:
-
Status: What state the subscription is in (and typically whether access should be granted).
-
Auto-renew: Whether the system is expected to renew at the next renewal point.
Common and expected combinations include:
|
Term Type |
Status |
Auto-Renew |
Explanation |
|---|---|---|---|
|
Payment Terms |
Active |
|
The subscriber turned off auto-renew, but the term has not ended yet; access continues. |
|
Dynamic Terms |
Active |
|
Dynamic Terms are always treated as auto-renewing. The |
|
Dynamic Terms |
Won't Renew |
|
Even after a deferred cancellation, the |
Additional behavior to be aware of:
-
"Won't Renew" is often not shown to end users on the front end to avoid confusion; they may still see "Active" while access remains valid.
-
For Dynamic Terms, the Auto-renew disablement date field will remain blank in reports, as Dynamic Terms do not support toggling auto-renew off. Use the Subscription Status and End Date fields to determine renewal status.
Dynamic Terms note: The is_in_trial boolean field is not populated for Dynamic Term subscriptions. To identify trial status or access period details for Dynamic Terms, use the subscription log report or the payment_billing_plan property from the /publisher/subscription/get API endpoint.
Grace Period and Retries
A typical renewal-failure lifecycle looks like this:
-
Renewal attempt fails → status may indicate Payment Failed / Payment Failure.
-
Retries occur (configuration-dependent).
-
If configured, a grace period may keep access active during retries.
-
If payment is not successfully captured by the end of retries/grace:
-
Subscription becomes Expired (or "expired due to payment error" in some webhook/status taxonomies).
-
Access ends.
-
This lifecycle applies to both Payment Terms and Dynamic Terms. Note that grace periods must be configured to be shorter than the billing period, and the maximum grace period is 60 days.
Reporting Guidance and Common Pitfalls
Counting "Active" Subscribers
If your goal is "who should have access during a period," you typically want subscriptions that are operationally active:
-
Include Active.
-
Include Won't Renew (they still have access until end date).
For Dynamic Terms, subscription reports currently display only data for the current access period. Pending renewals after an Action Manager migration will not appear in reports until the new billing cycle begins.
Interpreting "Expired" in Reports
"Expired" in reporting generally means subscriptions that ended during the specified period (term ended without renewal), including scenarios like:
-
Auto-renew disabled prior to term end (Payment Terms)
-
Deferred cancellation reaching the end of billing period (Dynamic Terms)
-
Manual/fixed-length term ended
-
Payment retries/grace period exhausted
-
No further access periods configured in a Dynamic Term
Avoiding Churn Misclassification for Dynamic Pricing Phases
Do not treat phase transitions inside a dynamic subscription as churn/loss. The subscription remains active through phase changes and only becomes churned when it is actually Canceled or Expired without renewal.
Additionally, be aware that for Dynamic Terms, the Auto-renew field in exports may always display as TRUE, regardless of whether the subscription will renew. Do not use this field alone to identify churn for Dynamic Term subscriptions — use Subscription Status (Won't Renew or Canceled) and the End Date column instead.
Exporting Lists That Match Visual Analytics
When reconciling exports with dashboards:
-
Verify whether Visual Analytics is grouping Won't Renew under Expired.
-
Filter by relevant dates (start date and end/access expiration date).
-
When looking for "current subscribers," leaving an "end date" filter blank (or using "currently active" logic) is often necessary, depending on the report type.
-
For Dynamic Terms, the Auto-renew disablement date field will be blank; use Subscription Status and End Date to identify subscribers who have canceled or won't renew.