Suspension and Recovery

When payments fail or a customer requests cancellation, the system follows a structured escalation path. This page explains the suspension flow, grace periods, recovery options, voluntary cancellation, and data retention.

The escalation timeline

Payment failure suspension

When a subscription payment fails, the system's response is governed by the PaymentRecoveryPolicy:

Setting	Default	Behavior
trigger	retry_exhausted	Suspend after all Stripe retries fail
anticipate_suspension	false	Suspend earlier for customers with poor history
suspended_to_cancelled_days	30	Days in suspended state before auto-cancellation
auto_reactivate_on_payment	true	Reactivate automatically when payment clears

What happens when an entitlement is suspended:

• The entitlement status transitions from active to suspended.
• Downstream resources are paused, not destroyed:
  • PLG: License remains on activated sites, but updates and new activations are blocked.
  • ENV: Environment stays running but may be marked read-only or degraded depending on admin action.
  • SVC: New service requests are blocked; in-progress requests continue.
  • Contracts: Remain visible but new work cannot be initiated.
• The customer is notified at each step of the escalation.

Grace period

The grace period is the window between suspension and cancellation. During this time:

1. The customer can still log in to the portal and see their entitlements (marked as suspended).
2. The customer can update their payment method and retry payment.
3. The system sends configurable reminders (governed by the NotificationPolicy).
4. If payment is recovered, the entitlement returns to active automatically (when auto_reactivate_on_payment is enabled).

The default grace period is 30 days. This can be customized per entitlement class, organization, product, or individual entitlement via the PaymentRecoveryPolicy.

Cancellation from payment failure

If the grace period expires without payment recovery:

1. The entitlement transitions from suspended to cancelled.
2. Downstream resources are deprovisioned according to the ProvisioningPolicy (deprovision_on_cancel setting).
3. The customer is notified of cancellation.
4. The data retention period begins.

Voluntary cancellation

When a customer voluntarily cancels:

1. The customer (or admin on their behalf) initiates cancellation.
2. The CancellationPolicy determines what happens:

Setting	Default	Behavior
portal_visibility_days	90	How long the cancelled entitlement remains visible in the portal
expired_to_cancelled_days	30	Grace period from expired to cancelled
data_retention_days	365	Days to retain operational data post-cancellation
data_action	export_and_delete	What to do with data after the retention period
offer_data_export	true	Offer data export to the customer

3. If the entitlement is subscription-based, the underlying WooCommerce Subscription is cancelled.
4. The entitlement transitions to cancelled.
5. If offer_data_export is enabled, the customer receives an export prompt.

Reactivation (win-back)

Even after cancellation, an entitlement can be reactivated:

1. The admin (or an automated win-back flow) reactivates the entitlement.
2. The entitlement transitions from cancelled back to active.
3. Downstream resources are re-provisioned.
4. The customer regains access immediately.

This supports scenarios like a customer returning after a break, a billing dispute resolved in the customer's favor, or a promotional win-back campaign targeting lapsed customers.

The same entitlement code is reused -- the customer's history is preserved.

Data retention

After cancellation, data handling follows the CancellationPolicy:

data_action value	What happens
export_and_delete	Customer is offered an export, then data is purged
archive	Data is moved to cold storage, accessible on request
retain	Data is kept indefinitely

Important: Fiscal data (invoices, tax invoices) follows legal retention requirements (LGPD/tax law) and is not governed by the CancellationPolicy. These records are retained for the legally mandated period regardless of the policy setting.

Notification timeline

Throughout the suspension and recovery process, the customer receives notifications:

Event	Notification
Payment failure	"Your payment failed. Please update your method."
Each retry attempt	"We tried to charge your card again."
Entitlement suspended	"Your access has been suspended."
During grace period	Configurable reminders (e.g., 15, 7, 1 day before cancellation)
Entitlement cancelled	"Your access has been cancelled."
Data export available	"Your data export is ready for download."

Notification channels and frequency are governed by the NotificationPolicy. See Policies for configuration.

Related pages

• Purchase and Renewal Flow -- Renewal and payment recovery
• Entitlement Activation -- What is provisioned (and deprovisioned)
• License Assignment -- PLG-specific suspension behavior
• Policies -- Policy configuration for recovery, cancellation, and notifications