> ## Documentation Index
> Fetch the complete documentation index at: https://alguna.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Plans

> Package priced products and commercial terms into a reusable offer for checkout, quotes and API-created subscriptions

A **plan** is a reusable, fully-specified offer: a set of [products](/docs/pricing/configure-products) with their [prices](/docs/pricing/pricing-models), 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](/docs/hosted/checkout), as the template a rep starts a [quote](/docs/quotes/create-quotes) from, or as the `plan_id` you pass when [creating a subscription](/docs/guides/first-subscription) via the API. See [How Alguna Works](/docs/concepts/how-alguna-works) for how plans relate to subscriptions.

<Tip>Configure products before creating plans. A plan references products by ID.</Tip>

***

## 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](/docs/entitlements/overview) |
| 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](https://app.alguna.io/plans) (or [Sandbox](https://app.sandbox.alguna.io/plans)) and click **New Plan**.

<Frame>
  <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/pricing/plan-creation.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=7c12eaac3e9c3e21f8c02888a0348e65" alt="Plan Creation Screen" width="1238" height="979" data-path="images/pricing/plan-creation.png" />
</Frame>

**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.

<Frame>
  <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/pricing/custom-terms.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=a9c40edf04748fe3dc05f75cf22e6ec9" alt="Plan Contract Terms" width="867" height="362" data-path="images/pricing/custom-terms.png" />
</Frame>

**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.

<Frame>
  <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/pricing/adding-products.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=058527493895c6353ed4155a633fdb78" alt="Add Products to Plan" width="1255" height="967" data-path="images/pricing/adding-products.png" />
</Frame>

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](/docs/api-reference/v2/2026-04-01/plans/create-a-plan) (`POST /plans`). This example packages a monthly platform fee with graduated API usage on a 12-month auto-renewing contract:

<CodeGroup>
  ```bash cURL theme={null}
  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" }
      ]
    }'
  ```

  ```python Python theme={null}
  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"])
  ```
</CodeGroup>

Read plans back with [List plans](/docs/api-reference/v2/2026-04-01/plans/list-plans) (`GET /plans`) and [Get a plan](/docs/api-reference/v2/2026-04-01/plans/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](/docs/pricing/pricing-models) explains each with worked examples; the [reference](/docs/api-reference/v2/subscriptions/pricing-models) has the request shape.

<Frame>
  <img src="https://mintcdn.com/alguna-20/SHr1INYd9aYWbwbe/images/pricing/adding-metered-products.png?fit=max&auto=format&n=SHr1INYd9aYWbwbe&q=85&s=eeaa4f814adb88129ad8fdb1ed4220bc" alt="Add Metered Products to Plan" width="859" height="578" data-path="images/pricing/adding-metered-products.png" />
</Frame>

***

## How plans are used

* **Self-serve checkout** — a buyer selects the plan in [hosted checkout](/docs/hosted/checkout) and the subscription is created without a human in the loop. Pass the `plan_id` when [creating a checkout session](/docs/api-reference/v2/2026-04-01/checkout-sessions/create-a-checkout-session).
* **Sales-led quotes** — a rep starts a [quote](/docs/quotes/create-quotes) from the plan and negotiates from there. The signed quote becomes the subscription.
* **API-created subscriptions** — pass `plan_id` to [`POST /subscriptions`](/docs/api-reference/v2/2026-04-01/subscriptions/create-a-subscription). Send `items` alongside `plan_id` to override individual prices or append add-ons for that customer; see [Creating a Subscription](/docs/api-reference/v2/examples/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](/docs/subscriptions/amendments) those individually.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Create your first subscription" icon="play" href="/docs/guides/first-subscription">
    Turn a plan into a live subscription.
  </Card>

  <Card title="Hosted checkout" icon="cart-shopping" href="/docs/hosted/checkout">
    Let customers buy a plan without sales.
  </Card>

  <Card title="Quotes" icon="file-contract" href="/docs/quotes/create-quotes">
    Negotiate from a plan and capture a signature.
  </Card>

  <Card title="Entitlements" icon="key" href="/docs/entitlements/overview">
    Provision feature access alongside the plan.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.