Manage Plans

A plan is a reusable, fully-specified offer: a set of products with their prices, plus the commercial terms that travel with them (contract length, renewal, trial, discount, spend thresholds, entitlements, invoice behaviour). Use a plan when the same offer will be sold more than once: as the thing a buyer picks in self-serve checkout, as the template a rep starts a quote from, or as the plan_id you pass when creating a subscription via the API. See How Alguna Works for how plans relate to subscriptions.

Configure products before creating plans. A plan references products by ID.

What a plan contains

Group	Fields	Notes
Identity	`name`, `description`, `currency`, `tags`	One currency per plan. Create a plan per currency to sell the same offer in several
Items	`items[]`	Each item is a standalone product (`product_id` + `price`) or a bundle (`bundle_id` + `name` + `items`)
Contract	`contract_period_type`, `contract_duration`	`fixed` (a set number of months) or `monthly_rolling` (no fixed term)
Renewal	`auto_renew`, `renewal_period_type`, `renewal_duration`	What happens when a fixed contract ends
Terms	`trial_period_days`, `discount`, `minimum_spend`, `maximum_spend`, `price_escalation`, `additional_terms`	Plan-wide guardrails; each price can also carry its own
Entitlements	`entitlements[]`	Feature flags, quotas and credit allocations provisioned with the plan. See Entitlements
Invoicing	`invoice_settings`, `payment_terms`	Auto-issue, auto-pay, email behaviour, memo and footer text, invoice payment terms such as `net_30`
Activation	`auto_activate`	Whether subscriptions created from the plan go straight to `active`

Create a plan

In the dashboard

Go to Plans (or Sandbox) and click New Plan.

Plan details — a name (visible to customers in checkout and on quotes) and a description. Contract details — choose Monthly Rolling (renews monthly, no fixed term) or Fixed (a set number of months), and for fixed contracts whether it auto-renews and for how long. Plan terms — optional terms that apply to the whole plan:

Trial period: days before billing starts.
Minimum spend: a floor the customer is billed each period regardless of usage. Can be billed in advance and drawn down, or trued up in arrears.
Maximum spend: a cap on what is billed in a period.
Discount: a percentage or fixed amount, for a set duration or rolling monthly until removed.
Price escalation: a percentage uplift applied every N months, for ramped multi-year deals.

Add products — click Add Product, search, select, and Save. For each product set the price: the amount and billing interval for a fixed product; the pricing model and tiers for a metered one.

Each product on the plan can also carry its own trial period, minimum spend, maximum spend and discount, which apply to that product only. Click Save Changes. The plan is then available for subscriptions, quotes and self-serve checkout.

Via the API

Use Create a plan (POST /plans). This example packages a monthly platform fee with graduated API usage on a 12-month auto-renewing contract:

curl -X POST https://api.alguna.io/plans \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Professional",
    "currency": "USD",
    "contract_period_type": "fixed",
    "contract_duration": 12,
    "auto_renew": true,
    "renewal_period_type": "fixed",
    "renewal_duration": 12,
    "trial_period_days": 14,
    "payment_terms": "net_30",
    "items": [
      {
        "product_id": "prod_032wMej82trlC5RulBsDJY",
        "price": {
          "type": "fixed",
          "fee_type": "fixed",
          "billing_direction": "advance",
          "billing_frequency": "recurring",
          "billing_interval": "monthly",
          "fixed_pricing_model": { "price_per_unit": "500.00", "units": 1 }
        }
      },
      {
        "product_id": "prod_04ab8Nej82trlC5RulBsDJY",
        "price": {
          "type": "graduated_tiered",
          "fee_type": "metered",
          "billing_direction": "arrears",
          "billing_interval": "monthly",
          "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"],
          "graduated_tiered_pricing_model": {
            "tiers": [
              { "min_units": 0, "max_units": 10000, "price_per_unit": "0.00", "fixed_fee": null },
              { "min_units": 10001, "max_units": null, "price_per_unit": "0.03", "fixed_fee": null }
            ]
          }
        }
      }
    ],
    "entitlements": [
      { "entitlement_key": "sso", "type": "boolean", "mode": "static", "value": "true" },
      { "entitlement_key": "seats", "type": "number", "mode": "static", "value": "25" }
    ]
  }'

import os

import requests

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

plan = {
    "name": "Professional",
    "currency": "USD",
    "contract_period_type": "fixed",
    "contract_duration": 12,
    "auto_renew": True,
    "renewal_period_type": "fixed",
    "renewal_duration": 12,
    "trial_period_days": 14,
    "payment_terms": "net_30",
    "items": [
        {
            "product_id": "prod_032wMej82trlC5RulBsDJY",
            "price": {
                "type": "fixed",
                "fee_type": "fixed",
                "billing_direction": "advance",
                "billing_frequency": "recurring",
                "billing_interval": "monthly",
                "fixed_pricing_model": {"price_per_unit": "500.00", "units": 1},
            },
        },
        {
            "product_id": "prod_04ab8Nej82trlC5RulBsDJY",
            "price": {
                "type": "graduated_tiered",
                "fee_type": "metered",
                "billing_direction": "arrears",
                "billing_interval": "monthly",
                "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"],
                "graduated_tiered_pricing_model": {
                    "tiers": [
                        {"min_units": 0, "max_units": 10000, "price_per_unit": "0.00", "fixed_fee": None},
                        {"min_units": 10001, "max_units": None, "price_per_unit": "0.03", "fixed_fee": None},
                    ]
                },
            },
        },
    ],
    "entitlements": [
        {"entitlement_key": "sso", "type": "boolean", "mode": "static", "value": "true"},
        {"entitlement_key": "seats", "type": "number", "mode": "static", "value": "25"},
    ],
}

response = requests.post("https://api.alguna.io/plans", headers=HEADERS, json=plan, timeout=10)
response.raise_for_status()
print(response.json()["id"])

Read plans back with List plans (GET /plans) and Get a plan (GET /plans/{id}). Plans are edited in the dashboard; the API has no update or delete for plans.

Pricing models on plan items

Each item’s price.type picks one of the eleven pricing models: fixed, unit, tiered, graduated_tiered, prepaid_tiered, prepaid_fixed_tiered, tiered_percentage, graduated_percentage, volume_percentage, expression and matrix. Pricing Models explains each with worked examples; the reference has the request shape.

How plans are used

Self-serve checkout — a buyer selects the plan in hosted checkout and the subscription is created without a human in the loop. Pass the plan_id when creating a checkout session.
Sales-led quotes — a rep starts a quote from the plan and negotiates from there. The signed quote becomes the subscription.
API-created subscriptions — pass plan_id to POST /subscriptions. Send items alongside plan_id to override individual prices or append add-ons for that customer; see Creating a Subscription.

A subscription created from a plan copies the plan’s items and terms into its first version. Editing the plan afterwards does not change existing subscriptions; amend those individually.

Next steps

Create your first subscription

Turn a plan into a live subscription.

Hosted checkout

Let customers buy a plan without sales.

Quotes

Negotiate from a plan and capture a signature.

Entitlements

Provision feature access alongside the plan.

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

What a plan contains

Create a plan

In the dashboard

Via the API

Pricing models on plan items

How plans are used

Next steps

Create your first subscription

Hosted checkout

Quotes

Entitlements

​What a plan contains

​Create a plan

​In the dashboard

​Via the API

​Pricing models on plan items

​How plans are used

​Next steps

Create your first subscription

Hosted checkout

Quotes

Entitlements

What a plan contains

Create a plan

In the dashboard

Via the API

Pricing models on plan items

How plans are used

Next steps