Skip to main content
Every subscription moves through a fixed set of statuses from creation to its end, and each transition has a billing consequence and a webhook. This guide walks the whole path in order (create, activate, change, renew, cancel) and points to the detailed page for each stage, so you can see the full arc before building against any one part of it. See How Alguna Works for where subscriptions sit in the quote-to-cash chain.

​
Why it matters

The lifecycle determines:
  • When customers are billed — invoices follow the status and the billing schedule
  • What customers can access — entitlements are only returned for active subscriptions
  • How changes apply — upgrades, downgrades and cancellations each have their own timing rules
  • What your revenue looks like — MRR, churn and expansion all derive from status transitions

​
Lifecycle states

​
1. Create

A subscription is created in draft, from a plan or with custom items, via the dashboard or POST /subscriptions. Nothing is billed while it is a draft, and it can be deleted with DELETE /subscriptions/{id}. Step-by-step: Create your first subscription.

​
2. Activate

Activation starts the contract: click Activate Subscription in the dashboard, call POST /subscriptions/{id}/activate, or pass auto_activate: true on create. For sales-led deals, Request Customer Signature sends the subscription as a quote; it becomes accepted on signature and active on the start date. In both cases subscription.activated fires, the billing cycle begins, and the first invoice is generated per the schedule.

​
3. Change

Once active, two kinds of change exist:

​
Upgrades and downgrades

Choose when the change lands: Example, upgrading 99/monthto99/month to 199/month on day 15 of a 30-day cycle with immediate:
Schedule downgrades and removals for next_billing_period. The customer keeps what they paid for, no credit is issued, and the lower charge starts with the next cycle.

​
Seats

For a fixed per-seat price, change units:
Preview any of these first with POST /subscriptions/{id}/changes/preview.

​
4. Renew

Renewal is governed by the subscription’s renewal block: auto_renew, period_type (fixed or monthly_rolling) and duration_months. These default from the plan and can be changed at any time with PATCH /subscriptions/{id}.
  • Auto-renew on: at the end of a fixed term a new term starts for duration_months, invoices continue, and subscription.started fires for the new period.
  • Auto-renew off: the subscription becomes expired at the end of the term.
  • Monthly rolling: there is no term to renew; the subscription continues month to month until cancelled.
To reprice at renewal, apply a change with effective: "next_term_renewal"; for an automatic annual uplift, set price_escalation (a percentage every interval_months). The next renewal date is on GET /subscriptions/{id}/billing-dates. For renewals that need a signature, issue a renewal quote.

​
5. Cancel

POST /subscriptions/{id}/cancel with a reason and an effective of immediate, end_of_term (end of the current billing period) or a date. subscription.cancelation_scheduled fires when the cancellation is recorded and subscription.canceled when it takes effect. A scheduled cancellation can be reverted while the subscription is still active (Revert Cancellation in the dashboard), which fires subscription.cancelation_reverted. Once canceled, the subscription is final; restart the customer with a new subscription. Full detail: Canceling Subscriptions.

​
Lifecycle webhooks

See Webhooks for payloads and setup.

​
Best practices

Downgrade at the boundary

Use next_billing_period for downgrades and removals to avoid credits.

Preview first

Call /changes/preview before applying anything mid-cycle.

Capture reasons

reason is required on cancel; use reason_description for the detail.

Act on webhooks, not polling

Grant access on subscription.activated, revoke on subscription.canceled.

​
Next steps

Proration

The calculation behind mid-cycle changes.

Versioning

Drafts, published versions and effective dates.