Suspend for Non-Payment

A payment failed. This recipe covers checking the suspension status, understanding the Payment Recovery Policy timeline, what the customer sees during suspension, and reactivating after payment is recovered.

Prerequisites

• WordPress admin access.
• An entitlement exists that has a failed payment (Stripe subscription renewal failed, or a manual payment was not received).

Steps

Part A: Identify the failed payment

Step 1. Go to MIDDAG Account > Entitlements and filter by status suspended. Alternatively, check MIDDAG Account > Logs for recent payment failure events.

Step 2. Open the suspended entitlement. Check the Payment History section for details on the failure:

• Failure date -- when the payment attempt failed.
• Failure reason -- card declined, insufficient funds, expired card, etc.
• Retry attempts -- how many times the system has retried.

Part B: Understand the Payment Recovery Policy timeline

Step 3. The system's response to payment failures is governed by the PaymentRecoveryPolicy. Check the policy values on the entitlement detail page:

Setting	Default	What it means
trigger	retry_exhausted	Suspend after all Stripe retries fail (not on first failure).
anticipate_suspension	false	If true, suspends sooner for customers with poor payment history.
suspended_to_cancelled_days	30	Days in suspended state before automatic cancellation.
auto_reactivate_on_payment	true	Reactivate automatically when payment clears.

Step 4. The typical timeline looks like this:

Day 0    Payment fails. Stripe retries per its schedule.
Day 3    Stripe retries (attempt 2).
Day 5    Stripe retries (attempt 3).
Day 7    All retries exhausted. Entitlement suspended.
Day 7-37 Grace period (30 days). Customer can update payment and retry.
Day 37   Grace period expires. Entitlement auto-cancelled.

The exact retry schedule depends on your Stripe settings. The grace period is configurable per entitlement, product, organization, class, or globally via the policy hierarchy. See Policies.

Part C: What happens during suspension

Step 5. When an entitlement is suspended, downstream resources are paused, not destroyed:

Class	What happens
PLG	License stays on activated sites, but updates and new activations are blocked.
ENV	Environment stays running. Admin may mark it read-only or degraded.
SVC	New service requests are blocked. In-progress requests continue.
ORD	No functional change, but the entitlement is marked as suspended in the portal.

Step 6. The customer is notified at each step:

• When the payment fails.
• When the entitlement is suspended.
• Reminder emails during the grace period (configurable via NotificationPolicy).
• When the grace period is about to expire.

Part D: What the customer sees

Step 7. The customer logs in to the portal and sees:

• Their entitlement is marked with a Suspended badge.
• A banner message explains why (payment failure) and what to do.
• A link to Update Payment Method takes them to the Stripe-hosted payment update page.
• A Retry Payment button is available if they have updated their card.

Step 8. The customer updates their payment method and retries. If the payment succeeds, the entitlement is reactivated automatically (when auto_reactivate_on_payment is enabled).

Part E: Reactivate after payment recovery

Step 9. If payment is recovered (customer updated their card, manual payment received, or Stripe retry succeeds):

• The entitlement status transitions from suspended back to active.
• Downstream resources resume: license updates are re-enabled, new service requests are allowed, etc.
• The customer and admin are notified of reactivation.

Step 10. To verify reactivation, open the entitlement and confirm:

• Status is active.
• Expiration Date was extended if the renewal payment was the one that failed and then recovered.
• Downstream resources are functional (license accepts new activations, service requests can be created).

Part F: Manual intervention

Step 11. If you need to reactivate manually (e.g., customer paid via bank transfer outside the system):

1. Open the entitlement detail page.
2. Click Reactivate Entitlement.
3. Optionally link the manual payment evidence (bank transfer receipt, etc.).
4. Set the new expiration date if extending the period.
5. Click Confirm.

Step 12. If the grace period expired and the entitlement was auto-cancelled, you can still reactivate it:

1. Open the cancelled entitlement.
2. Click Reactivate (available for a configurable period after cancellation).
3. Process or link a payment.
4. The entitlement returns to active.

Expected result

• The suspended entitlement is reactivated after payment recovery.
• Downstream resources (licenses, services, environments) resume normal operation.
• The customer sees the active status and renewed expiration date in the portal.
• If not recovered within the grace period, the entitlement is auto-cancelled per policy.

Further reading

• Suspension and Recovery -- the conceptual flow behind suspension.
• Policies -- Payment Recovery Policy and Notification Policy configuration.
• Handle Offboarding -- what happens if the entitlement is cancelled.