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

# Run SaaS Subscriptions

> Set up recurring billing with monthly/yearly plans, trials, and cancellation handling

## Who Is This For?

This guide is for merchants who sell subscription-based services or products with recurring billing. Common examples include:

| Business Type     | Examples                                             |
| ----------------- | ---------------------------------------------------- |
| SaaS Products     | Project management tools, CRM, analytics platforms   |
| Content Platforms | Online learning, premium newsletters, media access   |
| Digital Services  | Cloud hosting, API access, design tools              |
| Membership        | Community access, premium support, exclusive content |

***

## Subscription Lifecycle

Before setting up, it helps to understand how subscriptions flow:

```
Trial → Active → (Renew each period) → Canceled → Expired
                       ↑                     ↓
                       └───── Reactivate ────┘
```

| Status      | What It Means                                             |
| ----------- | --------------------------------------------------------- |
| `trialing`  | Customer is in a free trial period                        |
| `active`    | Paying customer, subscription is active                   |
| `past_due`  | Payment failed, Waffo is retrying automatically           |
| `canceling` | Customer canceled, but still has access until period ends |
| `canceled`  | Subscription has fully ended                              |

***

## Step 1: Create Subscription Products

You'll typically create multiple products for different pricing tiers (e.g., Free, Pro, Enterprise).

<Steps>
  <Step title="Go to Products">
    In your Dashboard, navigate to **Products** from the sidebar.

    <Frame>
      <img src="https://mintcdn.com/waffo/5dRlk76Jm-9Zm6Tj/images/guides/products-list.png?fit=max&auto=format&n=5dRlk76Jm-9Zm6Tj&q=85&s=2644c3ec77acc0f3c7769bdd91553232" alt="Products list page" width="1440" height="900" data-path="images/guides/products-list.png" />
    </Frame>
  </Step>

  <Step title="Create a Subscription Product">
    Click **Create Product** and select **Subscription** as the product type.

    <Frame>
      <img src="https://mintcdn.com/waffo/5dRlk76Jm-9Zm6Tj/images/guides/create-subscription-product.png?fit=max&auto=format&n=5dRlk76Jm-9Zm6Tj&q=85&s=93bbcb12bcebb09ce92d5e961981986a" alt="Create subscription product form" width="1440" height="900" data-path="images/guides/create-subscription-product.png" />
    </Frame>
  </Step>

  <Step title="Configure Pricing">
    * **Name**: Your plan name (e.g., "Basic Plan", "Pro Plan")
    * **Billing Period**: Choose monthly, quarterly, or yearly
    * **Price**: Set the recurring price
    * **Description**: What's included in this plan

    <Tip>
      Create separate products for each billing period. For example, create both a monthly and yearly version of the same plan.
    </Tip>
  </Step>

  <Step title="Save and Activate">
    Click **Save**. The product starts in test mode. Activate it when ready.
  </Step>
</Steps>

***

## Step 2: Organize Plans with Product Groups

If you have multiple tiers (Free, Pro, Enterprise), use **Product Groups** to organize them.

<Steps>
  <Step title="Create a Product Group">
    Go to **Products** and create a new product group (e.g., "Pricing Plans").
  </Step>

  <Step title="Add Products to the Group">
    Select the subscription products that belong together. This helps manage pricing tiers as a unit.
  </Step>

  <Step title="Configure Group Settings">
    * **Shared Trial**: If enabled, a customer who used a trial on one plan can't get another trial on a different plan in the same group.
  </Step>
</Steps>

<Note>
  Product groups are optional but recommended if you offer multiple pricing tiers. They prevent trial abuse and simplify management.
</Note>

***

## Step 3: Share and Start Selling

Just like one-time products, subscription products get a checkout link.

### Share the Checkout Link

Copy the checkout link from the product detail page:

```
https://checkout.waffo.ai/your-store/my-product
```

### Build a Pricing Page

Create a pricing page on your website that links to each plan's checkout URL:

> Prices below are examples only. Set them based on your actual business.

| Plan       | Price      | Checkout Link                                          |
| ---------- | ---------- | ------------------------------------------------------ |
| Basic      | \$9/month  | `https://checkout.waffo.ai/your-store/basic-plan`      |
| Pro        | \$29/month | `https://checkout.waffo.ai/your-store/pro-plan`        |
| Enterprise | \$99/month | `https://checkout.waffo.ai/your-store/enterprise-plan` |

***

## Step 4: Monitor Subscriptions

### Subscriptions Dashboard

Navigate to **Subscriptions** in the sidebar to see all active, trialing, and canceled subscriptions.

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

Each subscription shows:

* Customer email
* Current plan
* Status (active, trialing, past\_due, etc.)
* Current period start and end dates
* Next billing date

### Subscription Detail

Click on any subscription to view details:

* Payment history
* Plan changes
* Cancellation details (if applicable)

***

## Step 5: Handle Cancellations

When a customer cancels, the subscription enters a **canceling** state. The customer keeps access until the current billing period ends, then it becomes **canceled**.

### What Happens Automatically

* Customer receives a cancellation confirmation email
* You receive a notification
* Access continues until the period ends
* No further charges are made

### View Cancellations in Dashboard

Filter subscriptions by **Canceling** or **Canceled** status to see who has left.

***

## Business Scenarios

<Note>
  The following are example scenarios. Adjust them to match your actual business.
</Note>

### Scenario 1: SaaS with Monthly and Yearly Plans

1. **Create products**: Create both monthly and yearly versions of the same plan
2. **Group them**: Create a product group to link them together
3. **Pricing page**: Link each option on your website
4. **Monitor**: Track MRR and churn in the Analytics page

### Scenario 2: Content Platform with Free Trial

1. **Create product**: Set up your subscription plan and price
2. **Enable trial**: Set a 14-day free trial period
3. **Share link**: Customer signs up and starts trial immediately
4. **After trial**: Automatically converts to paid subscription, or expires if they don't add payment

### Scenario 3: API Service with Tiered Plans

1. **Create products**: Create a subscription product for each tier with different API call quotas and prices
2. **Group them**: Create a product group with shared trial
3. **Integrate webhooks**: Grant appropriate API limits based on which plan the customer subscribes to

***

## Going Further: Code Integration

### When You Need Code

* **Access control**: Check subscription status in your app to gate features
* **Automated provisioning**: Use webhooks to automatically create accounts or adjust limits
* **Custom cancellation flows**: Build in-app cancellation with feedback collection

### Key Webhook Events

| Event                    | When It Fires               |
| ------------------------ | --------------------------- |
| `subscription.activated` | New subscription started    |
| `subscription.updated`   | Plan changed or renewed     |
| `subscription.canceled`  | Subscription fully ended    |
| `order.completed`        | Recurring payment processed |
| `subscription.past_due`  | Payment attempt failed      |

For webhook setup, see the [Webhooks guide](/guides/webhooks). For API details, see the [API Reference](/api-reference/introduction).

***

## Testing

<Steps>
  <Step title="Enable Test Mode">
    Toggle to test mode in your Dashboard.
  </Step>

  <Step title="Subscribe with Test Card">
    Use `4576 7500 0000 0110` to simulate a successful subscription.
  </Step>

  <Step title="Check Subscription">
    Verify the subscription appears in your Subscriptions page with the correct plan and status.
  </Step>

  <Step title="Test Cancellation">
    Cancel the test subscription and verify it transitions to canceling → canceled.
  </Step>
</Steps>

***

## Launch Checklist

* [ ] Subscription products created for each plan/tier
* [ ] Product group set up (if multiple tiers)
* [ ] Pricing page links to correct checkout URLs
* [ ] Test subscription flow works end-to-end
* [ ] Cancellation flow tested
* [ ] Notification emails look correct
* [ ] Products published to production

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Set Up Webhooks" icon="webhook" href="/guides/webhooks">
    Automate access control with subscription event notifications
  </Card>

  <Card title="AI Product Billing" icon="chart-line" href="/guides/ai-billing">
    Combine subscriptions with metered usage
  </Card>
</CardGroup>