> ## 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, with renewals that run automatically against the gateway the buyer used at signup.

## Billing intervals

You can bill weekly, monthly, yearly, or on 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 applies automatically when the trial ends. The buyer does not need to take any action. 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 can cancel at any time 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. There is 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 is 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 it takes any other action. The default grace period is **7 days** (configurable per shop). During grace:

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

After the grace period, if the renewal has not 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 only 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 at any time. The buyer keeps the same plan and pricing.