Managing Subscriptions

A subscription binds a customer to an agreed offer: which products, at what prices, on what contract and billing terms. It is the object every downstream stage reads from: usage is rated against its prices, invoices are generated from its billing schedule, entitlements are read from it, and revenue schedules are derived from it. Subscriptions are versioned, so the agreement can change over time without losing history. See How Alguna Works for the full chain. There are three ways a subscription comes into existence, and all three produce the same object:

From a plan, in the dashboard or via POST /subscriptions. See Create your first subscription.
From a signed quote, for sales-led deals. See Sending Quotes.
From self-serve checkout, created automatically when the buyer completes hosted checkout.

The subscription object

Field	What it holds
`customer_id`, `plan_id`	Who it belongs to and, if it came from one, the plan it was created from
`currency`	ISO 4217 code. Defaults to the customer’s currency when created from a plan
`contract`	`period_type` (`fixed` or `monthly_rolling`), `start_date`, `duration_months`, `end_date`
`billing`	`first_billing_date`, `auto_issue_invoices`, `auto_pay_invoices`, `payment_terms` (for example `net_30`)
`renewal`	`auto_renew`, `period_type`, `duration_months`
`trial_period_days`, `discount`, `minimum_spend`, `maximum_spend`, `price_escalation`	Subscription-level commercial terms
`status`	Where it is in its lifecycle (below)
`current_version_id`	The published version currently in effect
`pending_changes`	Versions that are drafted or scheduled but not yet in effect
`metadata`	Your own key-value data

The priced items themselves are not on the subscription; they live on its versions. Read the current ones with GET /subscriptions/{id}/versions/current.

Subscription statuses

Status	Meaning
`draft`	Created but not started. Editable, deletable, not billed.
`pending_approval`	Sent for internal approval because a rule matched.
`rejected`	An approver declined it. Edit and resubmit.
`sent`	Sent to the customer for review and signature as a quote.
`accepted`	Signed by the customer (and countersigned, if required). Activates on the contract start date.
`active`	Live and billing.
`paused`	Billing is suspended until the subscription resumes.
`canceled`	Ended by a cancellation. Terminal.
`expired`	Reached the end of a fixed term without renewing.
`withdrawn`	Pulled back before it became active.

Subscriptions list with subscription ID, name, customer, status and updated date columns and a New Subscription button

Create and activate via the API

Create from a plan and activate in one call with auto_activate: true. Omit it to create a draft you can review first, then call Activate a subscription.

curl -X POST https://api.alguna.io/subscriptions \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "wcqYrqfE",
    "plan_id": "pln_032wMej82trlC5RulBsDJY",
    "contract": { "start_date": "2026-10-01" },
    "auto_activate": true
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

response = requests.post(
    "https://api.alguna.io/subscriptions",
    headers=HEADERS,
    json={
        "customer_id": "wcqYrqfE",
        "plan_id": "pln_032wMej82trlC5RulBsDJY",
        "contract": {"start_date": "2026-10-01"},
        "auto_activate": True,
    },
    timeout=10,
)
response.raise_for_status()
subscription = response.json()
print(subscription["id"], subscription["status"])

To define the priced items in the request instead of using a plan, or to override individual plan prices for one customer, see Creating a Subscription.

Activate via the dashboard

Once the products are added, click Activate Subscription. You are offered two options:

Activate Subscription — use this when the contract was signed outside Alguna and billing should start on the contract start date.
Request Customer Signature — sends the subscription to the customer as a quote for acceptance and e-signature. It activates only once the customer signs and the start date is reached. See Sending Quotes.

After activation

Alguna emits subscription.activated when the subscription goes live, subscription.started at the start of each billing period, subscription.updated when a top-level attribute changes, and subscription.version.updated when pricing changes through a version. See Webhooks.

To…	See
Change name, terms, discount, thresholds or metadata	Editing Subscriptions
Understand drafts, published versions and effective dates	Versioning
Add, remove or re-price products mid-term	Amendments
Know what a mid-period change will cost	Proration
End the subscription	Canceling Subscriptions
Read what the customer is allowed to do	Entitlements
Walk the whole lifecycle end to end	Subscription Lifecycle

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Managing Subscriptions

The subscription object

Subscription statuses

Create and activate via the API

Activate via the dashboard

After activation

​The subscription object

​Subscription statuses

​Create and activate via the API

​Activate via the dashboard

​After activation

The subscription object

Subscription statuses

Create and activate via the API

Activate via the dashboard

After activation