> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reorderjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancellation & Retention

> Cancellation cases let you run retention offers before finalizing a cancellation. Learn how pause, discount, and bonus offers work and when to finalize.

When a customer wants to cancel their subscription, Reorder gives you the opportunity to intervene before the cancellation is finalized. A cancellation case captures the customer's intent to cancel and opens a structured workflow where you can apply retention offers — such as a temporary pause, a discount, or a bonus — to change the customer's mind. If no offer works, you finalize the cancellation with a recorded reason.

## When a cancellation case is created

A cancellation case can be started for any subscription in `active`, `paused`, or `past_due` status. Subscriptions that are already `cancelled` cannot open a new case.

Cases are created in two ways:

* **Store API**: A customer initiates a cancellation request through `POST /store/customers/me/subscriptions/:id/cancellation`. This creates a case and surfaces it in the Admin cancellations queue for operator handling.
* **Admin**: An operator opens a case directly from the subscription detail page.

Only one active cancellation case can exist per subscription at a time.

## Cancellation case states

| Status     | What it means                                                           |
| ---------- | ----------------------------------------------------------------------- |
| `open`     | The case is active and awaiting a retention decision or finalization    |
| `paused`   | A pause retention offer was accepted — the subscription is now paused   |
| `retained` | A discount or bonus offer was applied — the subscription remains active |
| `canceled` | The cancellation was finalized — the subscription is now cancelled      |

## Retention offer types

Before finalizing a cancellation, you can apply one or more retention offers to try to keep the subscriber. Each offer is recorded as a retention offer event in the case history.

| Offer type | What it does                                                                                                                            |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `pause`    | Pauses the subscription for a defined period. The case closes as `paused`.                                                              |
| `discount` | Applies a discount to future renewals. The case closes as `retained` and the subscription stays active.                                 |
| `bonus`    | Adds a bonus — such as a free product or credit — to the next renewal. The case closes as `retained` and the subscription stays active. |

<Note>
  Applying a pause offer closes the cancellation case as `paused`. Applying a discount or bonus offer closes the case as `retained`. In both outcomes, the subscription is not cancelled.
</Note>

## Finalizing a cancellation

If no retention offer resolves the case, you finalize the cancellation from the case detail page. Finalization requires a churn reason to be recorded before it proceeds.

When you finalize:

* The subscription moves to `cancelled`.
* `cancel_effective_at` is set.
* `next_renewal_at` is cleared, stopping all future renewal scheduling.
* The case closes as `canceled`.

## Cancellation reason categories

When you record or update a churn reason on a case, you classify it into a reason category. These categories are used for reporting and help surface churn patterns in the Admin analytics. Common categories include product dissatisfaction, pricing concerns, and temporary pauses versus permanent cancellations.

You can update the reason and category on an open case at any time without affecting the case status.

## Coexistence with dunning

A cancellation case and a dunning case can be active for the same subscription simultaneously. A subscriber in `past_due` status — where dunning is actively retrying the payment — can still enter a retention flow or be finalized for cancellation. Dunning owns the payment recovery process; the cancellation case owns the churn handling process. Neither domain takes over the other's state.

<Warning>
  Finalizing a cancellation while a dunning case is active will cancel the subscription, but the dunning case retains its own closure flow. You will still need to resolve the dunning case separately.
</Warning>

## Store API self-service cancellation

Customers can initiate their own cancellation request through the Store API without needing Admin intervention to start the process. The `POST /store/customers/me/subscriptions/:id/cancellation` endpoint creates a cancellation case and routes it to the Admin queue, where your team can review it and apply a retention offer or proceed with finalization.

This flow keeps the customer-facing experience smooth while giving your team control over the final outcome.