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

# Subscription Lifecycle

> Understand how subscriptions move through their lifecycle

Every subscription goes through a series of states from creation to cancellation. Understanding this lifecycle helps you manage customer relationships effectively and ensure proper billing at each stage.

***

## Why Lifecycle Matters

The subscription lifecycle determines:

* **When customers are billed** - Invoices generate based on lifecycle events
* **What access customers have** - Features unlock/lock based on status
* **How changes are applied** - Upgrades, downgrades, and cancellations follow specific rules
* **What your revenue looks like** - MRR, churn, and expansion metrics depend on lifecycle tracking

***

## Lifecycle States

```mermaid theme={null}
stateDiagram-v2
    [*] --> Draft: Create
    Draft --> PendingApproval: Submit for approval
    Draft --> Active: Activate
    PendingApproval --> Active: Approve
    PendingApproval --> Draft: Reject
    Active --> Active: Upgrade/Downgrade
    Active --> Canceled: Cancel
    Active --> Active: Renew
    Canceled --> [*]
```

| Status               | Description                             | Billing           | Customer Access |
| -------------------- | --------------------------------------- | ----------------- | --------------- |
| **Draft**            | Subscription created but not started    | No billing        | No access       |
| **Pending Approval** | Awaiting internal approval (if enabled) | No billing        | No access       |
| **Active**           | Customer is subscribed and being billed | Active billing    | Full access     |
| **Canceled**         | Subscription ended                      | No future billing | Access revoked  |

***

## Creating a Subscription

1. Navigate to **Customers** → select customer
2. Click **Add Subscription**
3. Select the plan
4. Configure billing details:
   * Start date (immediate or scheduled)
   * Billing frequency
   * Contract term (if applicable)
5. Click **Create**

The subscription is created in **Draft** status.

***

## Activating a Subscription

A draft subscription must be activated to start billing:

1. Open the subscription
2. Review the configuration
3. Click **Activate**

Once activated:

* The customer's billing cycle begins
* The first invoice is generated (if applicable)
* The `subscription.activated` webhook fires

***

## Plan Changes (Upgrades & Downgrades)

### Upgrading a Customer

When a customer needs more features or capacity:

1. Open the subscription
2. Click **Change Plan**
3. Select the new (higher) plan
4. Choose when the change takes effect:
   * **Immediately** - Proration applies
   * **At renewal** - No proration, changes at next billing cycle
5. Review the proration preview
6. Click **Confirm**

### Proration Explained

When a customer upgrades mid-cycle, Alguna calculates the fair amount:

| Scenario               | Calculation                   |
| ---------------------- | ----------------------------- |
| Day 15 of 30-day cycle | 15 days remaining             |
| Old plan: \$99/month   | Credit: 15 × $3.30 = $49.50   |
| New plan: \$199/month  | Charge: 15 × $6.63 = $99.45   |
| **Net charge**         | $99.45 - $49.50 = **\$49.95** |

### Downgrading a Customer

When a customer moves to a lower plan:

1. Open the subscription
2. Click **Change Plan**
3. Select the new (lower) plan
4. Choose timing:
   * **Immediately** - Credit applied to balance
   * **At renewal** - Recommended to avoid complexity
5. Click **Confirm**

<Tip>
  **Best practice:** Schedule downgrades for the end of the billing period. This avoids credit calculations and matches customer expectations.
</Tip>

***

## Adding or Removing Seats

For per-seat pricing models:

1. Open the subscription
2. Click **Update Quantity**
3. Enter the new seat count
4. Choose when the change applies
5. Review proration (for immediate changes)
6. Click **Confirm**

| Change       | Timing     | Billing Impact                       |
| ------------ | ---------- | ------------------------------------ |
| Add seats    | Immediate  | Prorated charge for remaining period |
| Add seats    | At renewal | Full charge starts next cycle        |
| Remove seats | Immediate  | Credit to balance                    |
| Remove seats | At renewal | Lower charge next cycle              |

***

## Renewals

### How Renewals Work

By default, subscriptions automatically renew at the end of each billing period:

1. Renewal date approaches
2. Invoice generates (per your invoice timing settings)
3. Payment collected (if auto-pay enabled)
4. New period begins

### Configuring Renewal Behavior

1. Navigate to **Settings** → **Subscriptions**
2. Configure defaults:
   * **Auto-renew** - On/off by default
   * **Renewal notice** - Days before renewal to notify customer
   * **Failed payment handling** - Retry schedule

### For Individual Subscriptions

1. Open the subscription
2. Click **Edit** → **Contract Terms**
3. Toggle **Auto-renew**
4. Set renewal term length (if different from initial)

***

## Cancellations

### Cancellation Options

| Type               | When It Ends         | Refund   | Use Case              |
| ------------------ | -------------------- | -------- | --------------------- |
| **End of period**  | At next renewal      | None     | Standard cancellation |
| **Immediate**      | Right now            | Optional | Urgent situations     |
| **Scheduled date** | Specific future date | None     | Contract end dates    |

### Canceling from Dashboard

1. Open the subscription
2. Click **Cancel Subscription**
3. Select cancellation type
4. Add cancellation reason (for analytics)
5. Choose refund option (if immediate)
6. Click **Confirm**

### What Happens After Cancellation

* **End of period**: Customer retains access until the period ends
* **Immediate**: Access revoked immediately
* Both trigger the `subscription.canceled` webhook when the cancellation takes effect

<Tip>
  Capture cancellation reasons to identify patterns. Common reasons (price, features, switching to competitor) help improve retention.
</Tip>

***

## Lifecycle Webhooks

Alguna sends webhooks at key lifecycle moments so your systems stay synchronized:

| Event                                | When It Fires                                  |
| ------------------------------------ | ---------------------------------------------- |
| `subscription.activated`             | Subscription becomes active                    |
| `subscription.started`               | New billing period begins (including renewals) |
| `subscription.cancelation_scheduled` | Customer scheduled a future cancellation       |
| `subscription.canceled`              | Subscription ended                             |
| `invoice.issued`                     | Invoice finalized and sent                     |
| `invoice.paid`                       | Payment successful                             |

See [Webhooks](/api-reference/webhooks) for payload details and setup.

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Schedule Downgrades" icon="calendar">
    Schedule downgrades for period end to avoid credit complexity.
  </Card>

  <Card title="Capture Reasons" icon="clipboard-question">
    Always collect cancellation reasons for retention analysis.
  </Card>

  <Card title="Send Confirmations" icon="envelope">
    Email customers when cancellations are scheduled with the effective date.
  </Card>

  <Card title="Retention Offers" icon="gift">
    Present offers during cancellation flow before it completes.
  </Card>
</CardGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Proration" icon="percent" href="/subscriptions/proration">
    Deep dive into proration calculations.
  </Card>

  <Card title="Versioning" icon="code-branch" href="/subscriptions/versioning">
    Learn about subscription versioning.
  </Card>
</CardGroup>