> ## 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.

# Renewals

> A renewal cycle represents one scheduled billing event for a subscription. Learn how cycles are executed, approved, failed, and how skipping a cycle works.

A renewal cycle is a single scheduled billing event for a subscription. When a subscription is created, Reorder schedules the first renewal cycle automatically. After each successful renewal, the next cycle is created and the subscription's `next_renewal_at` date advances. Every renewal cycle has its own status, attempt history, and — when applicable — approval state.

## Renewal cycle statuses

| Status       | What it means                                                                          |
| ------------ | -------------------------------------------------------------------------------------- |
| `scheduled`  | The cycle is due in the future and waiting to be processed                             |
| `processing` | The execution workflow is currently running for this cycle                             |
| `succeeded`  | The renewal completed successfully and a new order was created                         |
| `failed`     | The renewal attempt failed — either due to a payment error or another processing issue |

<Note>
  A `failed` cycle that failed because of a payment error will trigger dunning automatically. See [Dunning](/concepts/dunning) for how payment recovery works.
</Note>

## How renewal execution works

Renewal cycles are processed by a background scheduler that runs every five minutes. The scheduler discovers all cycles with status `scheduled` or `failed` whose `scheduled_for` date is in the past and runs the execution workflow for each.

During execution, the workflow:

1. Validates that the linked subscription is eligible (not paused or cancelled).
2. Checks whether approval is required and has been granted.
3. Re-validates the current plan offer policy, including any pending plan changes.
4. Creates the renewal order using the subscription's current plan and shipping address.
5. Applies any approved pending plan change to the subscription's active cadence.
6. Updates `next_renewal_at` and creates the next scheduled renewal cycle.

<Warning>
  Paused and cancelled subscriptions are not eligible for renewal execution. Renewal cycles for ineligible subscriptions are skipped by the scheduler.
</Warning>

## The approval flow

Some renewal cycles require admin approval before they can execute — for example, when a plan change is pending and your configuration requires human review before the change takes effect. When approval is required, the cycle will not run until an admin approves it.

Approval statuses:

| Status     | What it means                                                           |
| ---------- | ----------------------------------------------------------------------- |
| `pending`  | The cycle is waiting for an approval decision                           |
| `approved` | The changes have been approved and the cycle may proceed                |
| `rejected` | The changes were rejected — the cycle will not apply the pending change |

You approve or reject a cycle from its detail page in the Admin renewals queue. Rejection requires a reason; approval does not.

## Manual force renewal

You can run a renewal cycle immediately from the Admin regardless of its scheduled date using the force renewal action. Force renewal uses the same execution workflow as the scheduler — the only difference is that it runs on demand.

<Note>
  If a cycle requires approval, you must approve it before a force renewal is allowed.
</Note>

## What happens when a renewal fails

When a renewal cycle fails after successfully creating the renewal order, Reorder starts a dunning case automatically. The subscription moves to `past_due` and the dunning scheduler begins retrying the payment according to the configured retry schedule.

If the renewal fails before an order is created — for example, due to a validation or eligibility error — dunning is not started. The cycle remains in `failed` state and can be retried manually using force renewal.

## Skipping a cycle

When you or a customer enables skip next cycle on a subscription, the upcoming renewal cycle is not cancelled — instead, it is skipped during execution and rescheduled for the following period. The `effective_next_renewal_at` field shows the projected delivery date after the skip, while `next_renewal_at` remains the internal billing anchor.

To skip the next delivery:

* Admin users can use the subscription detail page.
* Customers can call `POST /store/customers/me/subscriptions/:id/skip-next-delivery`.

The `skip_next_cycle` flag resets to `false` after the skip is applied.