Renewals

Renewals extend an entitlement's validity without creating a new entitlement. The same entitlement code persists across all renewal cycles. MIDDAG Account supports both automatic and manual renewal flows.

Auto-renewal

For subscription-based products, WooCommerce Subscriptions and Stripe handle the recurring billing. MIDDAG Account responds to the results:

1. Before expiration -- The Renewal Policy's grace_days_pre_expiry setting (default: 7 days) determines when the system attempts to charge the stored payment method.
2. Charge succeeds -- WooCommerce creates a renewal order with status Completed. The entitlement's expiration date is extended by the billing period. Status remains active.
3. Charge fails -- The Payment Recovery Policy takes over (see Payment failure below).

WooCommerce Subscriptions manages the complexity of recurring billing -- proration, retry schedules, and payment method updates. MIDDAG Account's subscription adapter translates these events into entitlement lifecycle transitions.

Manual renewal

For non-subscription entitlements, or when auto-renewal is disabled:

1. Renewal reminders are sent at configurable intervals before expiration (default: 30, 7, and 1 day before).
2. The customer initiates renewal from the portal, which starts a new payment flow.
3. On successful payment, the entitlement is renewed with an updated expiration date.

Manual renewal creates a new WooCommerce order, which flows through the same pipeline as any other order. The difference is that the provisioning service recognizes the existing entitlement and extends it rather than creating a new one.

Early renewal

Customers can renew before the current period ends. The early_renewal_days setting (default: 30) controls how far in advance renewal is allowed. When renewed early, the new period is added to the existing expiration date -- the customer does not lose any remaining time.

Grace period

When an entitlement reaches its expiration date without a successful renewal:

1. The entitlement transitions to expired.
2. A grace period begins, governed by the Renewal Policy.
3. During the grace period, the customer can still renew at the original price.
4. If the grace period passes without renewal, the Cancellation Policy takes over -- after expired_to_cancelled_days (default: 30 days), the entitlement is automatically cancelled.

During the grace period, downstream resource behavior depends on the entitlement class:

Class	Grace period behavior
PLG	License key remains valid, download access continues
ENV	Environment stays accessible but may be flagged for decommission
SVC	Service requests can still be submitted, but new credits are paused

Renewal notification timeline

The Notification Policy controls when reminders are sent. The default timeline:

When	Notification
30 days before expiration	First renewal reminder
7 days before expiration	Second renewal reminder
1 day before expiration	Urgent renewal reminder
On expiration	Expiration notice ("your entitlement has expired")
During grace period	Grace period reminder ("you still have time to renew")
Grace period ending	Final notice ("access will be cancelled in X days")

These intervals are configurable per class, organization, product, or individual entitlement through the policy override hierarchy.

Price changes on renewal

The Renewal Policy's renewal_pricing setting controls what price the customer pays at renewal:

Setting	Behavior
same	Renews at the original purchase price (default for PLG, ENV, ORD, AFL, EDU)
current	Renews at the current catalog price (default for SVC class)

When set to current, the customer is notified in the renewal reminder if the new price differs from their current price. This is particularly relevant for service contracts where rates may be adjusted annually.

Regardless of the setting, an admin can always override the renewal price for a specific entitlement.

Payment failure

When a renewal payment fails:

1. Stripe retries automatically according to its configured retry schedule.
2. After retries are exhausted, the Payment Recovery Policy determines the next step.
3. By default (trigger: retry_exhausted), the entitlement moves to suspended.
4. The customer is notified at each failed attempt and when the entitlement is suspended.
5. If payment is eventually recovered, the entitlement returns to active automatically (auto_reactivate_on_payment: true).
6. If payment is not recovered within suspended_to_cancelled_days (default: 30 days), the entitlement is cancelled.

For the full suspension and recovery timeline, see the Payment Status Mapping page.

Related pages

• Orders and Entitlements -- how orders create entitlements
• Refunds and Cancellations -- cancellation impact on entitlements
• Payment Status Mapping -- status transitions across all three systems
• Purchase and Renewal Flow -- full pipeline walkthrough