Subscription 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

---

​

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:

​

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

---

​

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

---

​

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

​

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

---

​

Lifecycle Webhooks

Alguna sends webhooks at key lifecycle moments so your systems stay synchronized: See Webhooks for payload details and setup.

---

​

Best Practices

---

​

Next Steps