# Retention rules

Reduce voluntary churn with targeted offers at cancellation.

Retention rules let you present a targeted offer when a customer attempts to cancel their subscription through the customer portal. You can target offers based on cancellation reason, subscription tenure, lifetime value, and other factors to retain customers before the cancellation completes.

## Enable retention rules

Retention rules replace the [retention coupon](https://docs.stripe.com/customer-management/cancellation-page.md#cancellation-deflection) setting in the customer portal configuration. When you enable retention rules, we automatically disable the existing retention coupon setting. Any previously configured retention coupons stop applying to cancellation flows.

To enable retention rules, go to the [Rules tab](https://dashboard.stripe.com/billing/retention/rules) in the Dashboard and turn on retention rules.

> You can’t use retention rules and retention coupons at the same time. If you need to revert to retention coupons, disable retention rules from the same page.

## Choose a rule type

You can create two kinds of retention rules:

- **All prices**: Applies as a default to any subscription price that doesn’t have its own rule.
- **Specific prices**: Applies only to subscriptions on one or more selected prices, letting you tailor the offer for those plans.

A price can only have one active rule at a time. When a customer cancels, Stripe evaluates rules in this order:

1. The rule for the specific price, if one exists.
2. The all prices rule, if no specific rule matches.

If neither applies, the customer proceeds through the standard cancellation flow with no offer.

## Add conditions

Conditions let you target offers to specific customer segments within a rule. You can combine multiple conditions to create more precise targeting. A customer must meet all conditions in a branch to receive the associated offer.

### Condition types

| Condition | Description | Example |
| --- | --- | --- |
| Cancellation reason | The reason the customer selects when canceling. It matches one or more reasons from the standard list or your custom reasons. | Show an offer only when the customer selects “Too expensive” |
| Months subscribed | How long the customer has been subscribed, in months. | Target customers subscribed for more than 6 months |
| Total billing spend | The total amount the customer has spent across all subscriptions and invoices received. | Offer a discount to customers who have spent more than 100 USD |
| Subscription status | The current status of the subscription. It matches one or more statuses: `active`, `trialing`, `past due`, or `paused`. | Exclude trialing customers from receiving offers |
| Subscription metadata | Custom key-value pairs on the `Subscription` object. | Exclude subscriptions where `signup_source` = `hackathon` |
| Customer metadata | Custom key-value pairs on the `Customer` object. | Target customers where `plan_tier` = `enterprise` |

### Evaluate conditions

Each rule can contain one or more condition branches. Stripe evaluates branches in the order you define them and presents the offer from the first branch where all conditions are met. If no branch matches, the customer continues through the cancellation flow without an offer.

## Configure an offer

When a condition branch matches, Stripe presents an offer to the customer before proceeding to cancellation. You can choose from the following offer types:

### Offer a discount

Offer a coupon to the customer to incentivize them to keep their subscription. You select the coupon when configuring the rule. This can be a percentage or fixed-amount discount applied to future billing cycles.

Discount coupons redeemed through retention offers are restricted to a single use per customer. If a customer has already redeemed a retention discount on a given subscription, they won’t see the same offer again.

### Offer a downgrade

If a customer wants to cancel, you can offer a lower-priced plan instead. If they accept the offer, their subscription switches to the new plan instead of canceling.

Before you can use downgrade offers, you must:

- [Enable switch plan](https://docs.stripe.com/customer-management/configure-portal.md#switch-plan) in your customer portal settings. If disabled, we don’t show the downgrade offer, even if a rule includes one.
- [Add marketing features](https://dashboard.stripe.com/products) to the product in your product catalog. We display these features to the customer to help them evaluate the offer. If the product has no marketing features, the customer doesn’t see any feature list in the offer.

Use the **Preview** option when configuring the rule to see how the offer appears to customers in the customer portal.

A condition branch can offer a discount or a downgrade, but not both.

## Example retention rule

For example, let’s say you have a Pro plan and want to retain long-tenured customers who cite price as their reason for canceling:

- **Rule type**: Specific price (Pro plan, monthly)
- **Condition branch 1**: Cancellation reason is “Too expensive” *and* months subscribed is greater than 6
- **Offer**: 30% discount coupon for 3 months
- **Condition branch 2**: Cancellation reason is “Too expensive” *and* months subscribed is greater than 3
- **Offer**: 15% discount coupon for 1 month

Customers who don’t match either branch proceed through the standard cancellation flow.