Refunds and Cancellations

Refunds and cancellations directly affect entitlement status and downstream resources. This page explains every scenario and how the Refund and Cancellation policies govern behavior.

Refund and cancellation flow

Full refund

When a WooCommerce order is fully refunded:

1. All entitlements linked to that order are moved to Cancelled status.
2. Downstream resources are deactivated:
   • PLG: License keys revoked, download access removed
   • ENV: Environment access suspended, flagged for decommission
   • SVC: Service contract terminated, remaining credits forfeited (per credits_on_refund: forfeit)
3. The organization dashboard reflects the change immediately.
4. A notification is sent to the organization confirming the cancellation.

The Refund Policy controls whether this happens automatically or requires admin approval:

Setting	Default	Description
refund_window_days	30	How many days after purchase a refund is allowed
auto_refund	false	Whether refunds are processed automatically (within auto_refund_max)
auto_refund_max	100.00	Maximum amount for automatic refund processing
cancel_entitlement	true	Whether the entitlement is automatically cancelled after full refund
credits_on_refund	forfeit	What happens to credits: forfeit, retain, or proportional
approval_required	admin	Who must approve: admin or none

Refund windows by class

Different entitlement classes have different default refund windows:

Class	Default refund window	Rationale
PLG	30 days	Standard software refund period
ENV	30 days	Standard refund period
SVC	0 days	Service contracts are non-refundable by default
ORD	30 days	Standard refund period
EDU	7 days	Service already consumed (training delivered)
AFL	30 days	Standard refund period

These are class-level defaults that can be overridden per organization, product, or individual entitlement.

Partial refund

Partial refunds do not automatically change entitlement status. The entitlement remains active. The admin can:

• Review the partial refund and decide whether to adjust the entitlement
• Downgrade the entitlement tier if the refund reflects reduced access
• Leave the entitlement unchanged if the refund was for a different reason (shipping, tax correction, goodwill)

Partial refund behavior can be customized through the Policy Engine in future releases.

Voluntary cancellation (by customer)

When a customer cancels a subscription through the portal:

1. The WooCommerce subscription status changes to Pending Cancellation.
2. The entitlement remains Active until the end of the current billing period.
3. At the end of the period, the entitlement transitions to Expired.
4. The Cancellation Policy's portal_visibility_days (default: 90 days) controls how long the expired entitlement remains visible in the customer's portal.
5. After expired_to_cancelled_days (default: 30 days), the entitlement is automatically cancelled.
6. If offer_data_export is enabled (default: true), the customer is offered a data export before final cancellation.
7. After data_retention_days (default: 365 days), operational data is purged. Fiscal data is retained according to legal requirements.

The customer can reactivate ("win-back") during the expired period by starting a new subscription, which reuses the same entitlement code.

Admin-initiated cancellation

An admin can cancel an entitlement at any time through the WordPress admin panel. This:

1. Immediately moves the entitlement to Cancelled status.
2. Deactivates all downstream resources.
3. Cancels the associated WooCommerce subscription (if applicable).
4. Sends a notification to the organization.

Admin cancellation bypasses the grace period and retention timeline.

Chargeback / dispute handling

When Stripe reports a chargeback or payment dispute:

1. The entitlement linked to the disputed payment is moved to Suspended.
2. The admin is notified of the dispute.
3. The admin can provide evidence to Stripe to contest the chargeback.
4. If the dispute is won: The entitlement returns to Active.
5. If the dispute is lost: The entitlement is moved to Cancelled and the refund is processed.

Chargeback handling is semi-automated -- the system suspends the entitlement immediately but relies on the admin to manage the dispute process in Stripe.

Data retention after cancellation

Data type	Retention period
Operational	365 days after cancellation (configurable)
Fiscal (invoices, tax invoices)	Legal minimum (not configurable)
Entitlement record	Retained indefinitely (audit trail)
Downstream resources (environments, files)	Purged after data retention period

Related pages

• Orders and Entitlements -- order-to-entitlement pipeline
• Renewals -- renewal mechanics
• Payment Status Mapping -- complete status mapping
• Taxes and Invoices -- invoice implications of refunds