Create Your First Subscription

This guide takes you from an empty account to a customer on an active subscription. You create a customer, put them on a plan, and activate; from there Alguna generates invoices on the plan’s schedule. Each step shows the dashboard path and the API call, so you can start by hand and automate later. If you have not yet created a plan, do Products and Plans first; for the wider picture see How Alguna Works.

Prerequisites: at least one plan, and an API key from Settings → Connections → Developers → API keys if you are using the API. All requests go to https://api.alguna.io with Authorization: Bearer <key> and Alguna-Version: 2026-04-01.

Step 1: Create a customer

A subscription needs a customer to bill. Dashboard: go to Customers, click New Customer, and fill in the name, primary contact email, country, billing currency and (optionally) address and external ID. Click Create. API: Create a customer. name and currency are required.

curl -X POST https://api.alguna.io/customers \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "currency": "USD",
    "aliases": ["acme-prod-42"],
    "contacts": [
      { "email": "finance@acme.example", "is_primary": true, "email_preferences": ["billing"] }
    ]
  }'

import os

import requests

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

customer = requests.post(
    "https://api.alguna.io/customers",
    headers=HEADERS,
    json={
        "name": "Acme Corp",
        "currency": "USD",
        "aliases": ["acme-prod-42"],
        "contacts": [
            {"email": "finance@acme.example", "is_primary": True, "email_preferences": ["billing"]}
        ],
    },
    timeout=10,
)
customer.raise_for_status()
customer_id = customer.json()["id"]

See Manage Customers for the full field list.

Step 2: Create the subscription from a plan

Dashboard: go to Subscriptions, click New Subscription, pick the customer and the plan, set the start date, review the pricing summary and save. The subscription is created in draft. API: Create a subscription with customer_id and plan_id. The plan’s items, contract and renewal terms are copied into the subscription’s first version; currency defaults to the customer’s.

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": "cust_abc123",
    "plan_id": "pln_032wMej82trlC5RulBsDJY",
    "name": "Acme Corp — Professional",
    "contract": { "start_date": "2026-10-01" }
  }'

import os

import requests

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

subscription = requests.post(
    "https://api.alguna.io/subscriptions",
    headers=HEADERS,
    json={
        "customer_id": "cust_abc123",
        "plan_id": "pln_032wMej82trlC5RulBsDJY",
        "name": "Acme Corp — Professional",
        "contract": {"start_date": "2026-10-01"},
    },
    timeout=10,
)
subscription.raise_for_status()
subscription_id = subscription.json()["id"]
print(subscription.json()["status"])  # draft

Step 3: Activate

Dashboard: open the subscription and click Activate Subscription, then Activate Subscription again to confirm (the other option, Request Customer Signature, sends it as a quote instead). API: Activate a subscription. Activation is idempotent. To skip this step entirely, pass "auto_activate": true in Step 2.

curl -X POST https://api.alguna.io/subscriptions/sub_abc123/activate \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

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

response = requests.post(
    "https://api.alguna.io/subscriptions/sub_abc123/activate",
    headers=HEADERS,
    timeout=10,
)
response.raise_for_status()

Your first subscription is live.

What happens after activation

The subscription’s status becomes active (or accepted until a future start date arrives).
A subscription.activated webhook fires, then subscription.started at the start of each billing period.
Invoices are generated on the billing schedule: advance charges at the start of the period, arrears and usage charges at the end. See Recurring invoices.
If auto_pay_invoices is on and the customer has a stored payment method, payment is collected; otherwise the invoice is sent for payment. invoice.issued and invoice.paid fire as that happens.

Optional: collect a payment method

For card or bank payments the customer needs a stored payment method. Two ways to get one:

Customer portal — create a portal session with POST /customer-portal-sessions and send the customer the URL, or send a portal link from the customer’s profile in the dashboard. See Customer Portal Integration.
Hosted checkout — create a checkout session with POST /checkout-sessions for the plan; the customer pays and the subscription is created in one step, which replaces Steps 2 and 3 for self-serve. See Hosted Checkout Integration.

Variations

Trial

Trials come from the plan’s trial_period_days, or set them on the subscription after creation with PATCH /subscriptions/{id} ("trial_period_days": 14). Billing starts when the trial ends.

Future start date

Set contract.start_date to a future date. You can activate immediately; the subscription waits in accepted and becomes active, with billing starting, on that date.

Custom line items instead of a plan

Send items with full price definitions and no plan_id, or send both to override individual plan prices for this customer. See Creating a Subscription for every pattern, including bundles.

Sales-led

If the deal needs a signature, build it as a quote and send it for e-signature. The signed quote activates as a subscription on its start date; no separate creation step is needed.

Managing the subscription

Read it back with GET /subscriptions/{id} (status, contract, billing, pending_changes) and its priced items with GET /subscriptions/{id}/versions/current. In the dashboard the subscription page shows status, billing period, line items, invoice history and activity.

To change it: Editing Subscriptions and Amendments.
To end it: Canceling Subscriptions.

Troubleshooting

Stuck in draft — subscriptions are created as drafts unless auto_activate is set. Activate it. No invoice yet — check the contract start date and billing.first_billing_date; advance charges are invoiced at the start of the period, arrears and usage charges at the end of it. Customer already has a subscription — customers can hold several subscriptions at once. This is normal.

Next steps

Subscription Lifecycle

Statuses, changes, renewals and cancellations end to end.

Usage metering

Send events for metered products.

Webhooks

React to activation and invoice events.

Entitlements

Gate features on the subscription.

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

Create Your First Subscription

Step 1: Create a customer

Step 2: Create the subscription from a plan

Step 3: Activate

What happens after activation

Optional: collect a payment method

Variations

Trial

Future start date

Custom line items instead of a plan

Sales-led

Managing the subscription

Troubleshooting

Next steps

Subscription Lifecycle

Usage metering

Webhooks

Entitlements

​Step 1: Create a customer

​Step 2: Create the subscription from a plan

​Step 3: Activate

​What happens after activation

​Optional: collect a payment method

​Variations

​Trial

​Future start date

​Custom line items instead of a plan

​Sales-led

​Managing the subscription

​Troubleshooting

​Next steps

Subscription Lifecycle

Usage metering

Webhooks

Entitlements

Step 1: Create a customer

Step 2: Create the subscription from a plan

Step 3: Activate

What happens after activation

Optional: collect a payment method

Variations

Trial

Future start date

Custom line items instead of a plan

Sales-led

Managing the subscription

Troubleshooting

Next steps