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

# Subscriptions

> Manage recurring billing and subscriber relationships

## Subscription Management

The Subscriptions page shows all recurring billing arrangements with your customers.

<Frame>
  <img src="https://mintcdn.com/waffo/5dRlk76Jm-9Zm6Tj/images/dashboard/subscriptions-list.png?fit=max&auto=format&n=5dRlk76Jm-9Zm6Tj&q=85&s=e1952d496dfb35c7bf74a8d95f733bbb" alt="Subscriptions List" width="1440" height="900" data-path="images/dashboard/subscriptions-list.png" />
</Frame>

## Subscription List

View all subscriptions in a detailed table:

| Column       | Description                      |
| ------------ | -------------------------------- |
| Status       | Current subscription status      |
| Product      | Product name and image           |
| Customer     | Subscriber email                 |
| Amount       | Subscription price with currency |
| Interval     | Billing frequency                |
| Next Billing | Next charge date                 |
| Created      | When subscription started        |

## Subscription Statuses

<CardGroup cols={2}>
  <Card title="Active" icon="check-circle" color="#22c55e">
    Subscription is live and billing normally.
  </Card>

  <Card title="Trialing" icon="flask" color="#3b82f6">
    Customer is in free trial period.
  </Card>

  <Card title="Past Due" icon="clock" color="#f59e0b">
    Payment failed, awaiting retry.
  </Card>

  <Card title="Canceling" icon="hourglass-half" color="#f59e0b">
    Cancellation requested, active until period end.
  </Card>

  <Card title="Expired" icon="calendar-xmark" color="#6b7280">
    Subscription has expired.
  </Card>

  <Card title="Canceled" icon="xmark" color="#ef4444">
    Subscription has been terminated.
  </Card>
</CardGroup>

## Billing Intervals

| Interval  | Billing Frequency | MRR Calculation |
| --------- | ----------------- | --------------- |
| Weekly    | Every 7 days      | Amount × 4.33   |
| Monthly   | Every month       | Amount × 1      |
| Quarterly | Every 3 months    | Amount ÷ 3      |
| Yearly    | Every 12 months   | Amount ÷ 12     |

## Filtering Subscriptions

| Filter   | Options                                                  |
| -------- | -------------------------------------------------------- |
| Status   | Active, Trialing, Past Due, Canceling, Expired, Canceled |
| Product  | Any subscription product                                 |
| Interval | Weekly, Monthly, Quarterly, Yearly                       |
| Customer | Search by email                                          |

## Subscription Details

Click on a subscription to view:

### Overview

* Subscription ID
* Status and status history
* Product details
* Pricing and currency
* Billing interval

### Billing Info

* Current period start/end
* Next billing date
* Payment method on file
* Billing history

### Customer

* Customer email
* Account details
* Other subscriptions from same customer

### Payment History

* All charges for this subscription
* Successful and failed attempts
* Refunds

## Managing Subscriptions

### Cancel Subscription

<Steps>
  <Step title="Open Subscription Details">
    Click on the subscription you want to cancel.
  </Step>

  <Step title="Click 'Cancel Subscription'">
    Find the button in the actions menu.
  </Step>

  <Step title="Confirm Cancellation">
    Cancellation takes effect at the end of the current billing period. The subscription enters "Canceling" status until the period ends, then becomes "Canceled".
  </Step>
</Steps>

<Note>
  The customer retains access until the end of their current paid billing period.
</Note>

### Resume Subscription

For subscriptions in "Canceling" status, a reactivation endpoint exists but currently returns 501 (not yet implemented).

## Subscription Metrics

### Statistics Cards

| Metric   | Description                     |
| -------- | ------------------------------- |
| MRR      | Monthly Recurring Revenue       |
| Active   | Count of active subscriptions   |
| Trialing | Count of subscriptions in trial |
| Canceled | Count of canceled (this period) |
| ARPU     | Average Revenue Per User        |

### MRR Calculation

MRR is calculated from all active subscriptions:

```
MRR = Σ (Subscription Amount × Interval Factor)

Where Interval Factor:
- Weekly: 4.33
- Monthly: 1
- Quarterly: 0.33
- Yearly: 0.083
```

## Failed Payments

When a subscription payment fails:

1. Status changes to "Past Due"
2. Automatic retry attempts (3 attempts over 7 days)
3. Customer notified via email
4. If all retries fail, subscription may cancel

### Dunning Emails

Automatic emails sent to customers:

* First failed payment notification
* Retry attempt reminders
* Final warning before cancellation
* Cancellation confirmation

## Trial Periods

For products with trials enabled:

| Field           | Description              |
| --------------- | ------------------------ |
| Trial Status    | Active trial indicator   |
| Trial Days      | Total trial length       |
| Days Remaining  | Time left in trial       |
| Conversion Date | When first charge occurs |

Track trial conversions:

* Trial → Active (converted)
* Trial → Canceled (churned before conversion)

### Platform Trial Protection

Waffo Pancake automatically tracks consumer trial history at the platform level. The actual trial days granted to a consumer may be less than the configured value if the consumer has used trials before. This prevents trial abuse without requiring any action from the merchant.

For Product Groups with **shared trial** enabled, trial usage is shared across all products in the group.

## Subscription Actions

<AccordionGroup>
  <Accordion title="Change Product/Plan">
    Upgrade or downgrade the subscription to a different product. Note: this endpoint currently returns 501 (not yet implemented).
  </Accordion>

  <Accordion title="Update Payment Method">
    Send customer a link to update their card on file.
  </Accordion>
</AccordionGroup>