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

# Subscriptions

> Recurring billing and subscription lifecycle for 86d: create, pause, resume, cancel, with provider-agnostic billing through @86d-store/payments.

<Warning>
  **Experimental.** This Module has no test or production evidence recorded yet. Read it, run it locally, and hold off on real Orders. See [maturity levels](/docs/resources/versioning).
</Warning>

The Subscriptions [Module](/docs/concepts/modules) manages the recurring-billing lifecycle on top of the [Products](/docs/modules/products) and [Payments](/docs/modules/payments) Modules. [Customers](/docs/resources/glossary#customer) can subscribe to a product, choose a billing interval, pause and resume, swap variants, and cancel. The Module schedules renewal charges through whichever payment provider you configure under `@86d-store/payments`.

**Source:** [`modules/subscriptions`](https://github.com/86d-store/86d/tree/main/modules/subscriptions) · **npm:** [`@86d-store/subscriptions`](https://www.npmjs.com/package/@86d-store/subscriptions)

## Installation

```sh theme={null}
86d module add subscriptions
```

The Module requires `@86d-store/products`, `@86d-store/orders`, and `@86d-store/payments` to be enabled.

## Configuration

```ts theme={null}
subscriptions({
  defaultBillingDay: "1",          // 1-28, day of month for renewals
  retryAttempts: "3",              // retries on failed renewal charge
  cancelOnFailure: "true",         // cancel after exhausting retries
  trialDaysDefault: "0",           // default trial period in days
});
```

## Store endpoints

| Method | Path                           | Description                       |
| ------ | ------------------------------ | --------------------------------- |
| `POST` | `/subscriptions`               | Create a subscription             |
| `GET`  | `/subscriptions/me`            | List the customer's subscriptions |
| `GET`  | `/subscriptions/me/:id`        | Get a single subscription         |
| `POST` | `/subscriptions/me/:id/pause`  | Pause renewals                    |
| `POST` | `/subscriptions/me/:id/resume` | Resume                            |
| `POST` | `/subscriptions/me/:id/swap`   | Swap variant                      |
| `POST` | `/subscriptions/me/:id/cancel` | Cancel                            |

## Admin endpoints

| Method | Path                              | Description                                           |
| ------ | --------------------------------- | ----------------------------------------------------- |
| `GET`  | `/admin/subscriptions`            | List subscriptions (filter by `status`, `customerId`) |
| `GET`  | `/admin/subscriptions/:id`        | Detail                                                |
| `POST` | `/admin/subscriptions/:id/refund` | Refund a renewal charge                               |
| `GET`  | `/admin/subscriptions/upcoming`   | Renewals due in the next N days                       |

## Lifecycle

```text theme={null}
trial -> active -> active (renews each cycle)
active -> paused -> active
active -> past_due -> active (after retry success) | cancelled (after retry exhaustion)
active -> cancelled
```

## Components

* `<SubscriptionPlanCard plan={...} />`: [Storefront](/docs/concepts/storefront) upsell card.
* `<SubscriptionsList />`: Customer self-service list.
* `<SubscriptionDetail id={...} />`: management UI with pause and cancel actions.

## Related pages

* [Payments](/docs/modules/payments)
* [Customers](/docs/modules/customers)
* [Memberships](/docs/modules/memberships) for paid access plans rather than per-product subscriptions
* [How commerce records relate](/docs/concepts/commerce-model)
* [Versioning and maturity](/docs/resources/versioning)
* [Glossary](/docs/resources/glossary)