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

# Subscriptions

> Recurring billing with trials, retries, and cancellation handling.

Set a product to subscription mode to charge buyers on a recurring schedule. Renewals run
automatically against the gateway the buyer used at signup.

## Billing intervals

Weekly, monthly, yearly, or any custom interval. Each renewal creates a new invoice; the buyer
sees a complete history from their customer dashboard.

## Trials

Offer a free trial or a discounted intro period. The full price kicks in automatically at the
trial end with no buyer action needed. Shoppex fires `subscription:trial:started` and
`subscription:trial:ended` webhook events so you can build flows around them.

## Plan changes

Buyers can upgrade or downgrade from their customer dashboard. Upgrades take effect immediately
with proration against the current period; downgrades take effect at the next renewal.

You can also change plans on the buyer's behalf from the subscription detail page in your
dashboard.

## Cancellation

Buyers cancel anytime from their customer dashboard. Cancellation behavior depends on the
gateway the buyer used:

* **Stripe / crypto** — cancellation is at period end. The buyer keeps access until the period
  they paid for runs out, then the subscription moves to canceled. No refund for the current
  period.
* **PayPal** — cancellation is immediate. PayPal cancels the subscription on their side right
  away and the Shoppex subscription moves to canceled at the same time. The buyer loses access
  immediately — there's no period-end grace.

You can also cancel on the buyer's behalf from **Subscriptions** in your dashboard.

## Failed renewals — grace period and auto-cancel

When a renewal payment fails, Shoppex enters a **grace period** before doing anything. The
default grace period is **7 days** (configurable per shop). During grace:

* The subscription stays active. The buyer retains access. Anything like a Discord role stays
  granted.
* The buyer is asked to update payment.

After the grace period, if the renewal hasn't been paid:

* The unpaid invoice is voided.
* The subscription moves to a past-due state.

Once the subscription has **two voided invoices in total** (cumulative across its lifetime,
not just consecutive), Shoppex automatically cancels it. Discord roles and other recurring
fulfillment are revoked at cancel time. The buyer can resubscribe at any time.

## Pause and resume

You can pause a subscription from the dashboard, which suspends renewals without cancellation.
Resume it any time. The buyer keeps the same plan and pricing.