> ## 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. # Creating a Subscription > Concrete patterns for creating a subscription: from raw pricing, from a plan, from a plan with overrides, and with bundles. The [`create-subscription`](/docs/api-reference/v2/2026-04-01/subscriptions/create-a-subscription) endpoint (`POST /subscriptions`) accepts three orthogonal inputs for the initial version's items. Pick the pattern that matches how pricing is owned. | Pattern | `plan_id` | `items` | Who owns the price definitions | | ----------------------------- | --------- | ---------------------------------------------------------- | --------------------------------- | | 1. Raw pricing | - | Full set of standalone and bundle items with inline prices | Your request body | | 2. From a plan | `pln_...` | - | The plan | | 3. From a plan with overrides | `pln_...` | Overrides and additions | The plan, then your body (merged) | | 4. With bundles | either | Bundle items with nested children | Depends on 1/2/3 above | ## Prerequisites Every request requires: * A customer ID (plain 8-char identifier, for example `wcqYrqfE`). See [`create-customer`](/docs/api-reference/v2/2026-04-01/customers/create-a-customer). * At least one product reference (`prod_...`) on each item, or a bundle reference (`bnd_...`) when using bundle items. See [`create-product`](/docs/api-reference/v2/2026-04-01/products/create-a-product). * Optionally a plan (`pln_...`) when using patterns 2 or 3. * Optionally a metric (`mtr_...`) when pricing metered items. Subscriptions are created in `draft` status. Call [`activate-subscription`](/docs/api-reference/v2/2026-04-01/subscriptions/activate-a-subscription) when you are ready for the subscription to go live, or pass `auto_activate: true` in the create request to skip the explicit activation step. ## Pattern 1: Raw pricing (no plan) Use this when the request body fully defines the priced item set. The `items` array is the complete set of items for the subscription's first version. ### 1a. Single standalone item with unit pricing ```bash theme={null} curl -X POST https://api.alguna.io/subscriptions \ -H "Authorization: Bearer sk_live_..." \ -H "Alguna-Version: 2026-04-01" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "wcqYrqfE", "currency": "USD", "name": "Acme Corp API Usage", "contract": { "period_type": "fixed", "duration_months": 12, "start_date": "2026-07-01" }, "items": [ { "product_id": "prod_032wMej82trlC5RulBsDJY", "price": { "type": "unit", "billing_interval": "monthly", "fee_type": "metered", "billing_direction": "arrears", "metric_ids": ["mtr_032wMej82trlC5RulBsDJY"], "unit_pricing_model": { "price_per_unit": "0.05" } } } ] }' ``` ### 1b. Mixed fixed and metered items A platform fee plus graduated API usage, with explicit billing configuration. ```json theme={null} { "customer_id": "wcqYrqfE", "currency": "USD", "name": "Acme Corp Enterprise", "contract": { "period_type": "fixed", "duration_months": 12, "start_date": "2026-07-01" }, "billing": { "first_billing_date": "2026-07-01", "auto_issue_invoices": true, "auto_pay_invoices": false, "payment_terms": "net_30" }, "items": [ { "product_id": "prod_032wMej82trlC5RulBsDJY", "price": { "type": "fixed", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "fixed_pricing_model": { "price_per_unit": "500.00", "units": 1 } } }, { "product_id": "prod_04ab8Nej82trlC5RulBsDJY", "price": { "type": "graduated_tiered", "billing_interval": "monthly", "fee_type": "metered", "billing_direction": "arrears", "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": 100000, "price_per_unit": "0.03", "fixed_fee": null }, { "min_units": 100001, "max_units": null, "price_per_unit": "0.02", "fixed_fee": null } ] } } } ] } ``` See the [pricing models reference](/docs/api-reference/v2/subscriptions/pricing-models) for the full set of supported `type` values and their required fields. ## Pattern 2: From a plan (no overrides) The simplest form. Pass a `plan_id` and the subscription is materialized from the plan's item set. You do not send `items` at all. `currency` defaults to the customer's configured currency when omitted. If you omit `contract.start_date`, the subscription remains unanchored while it is still draft and the contract start date is set when the subscription is activated. Pass `contract` explicitly when you want to override the plan's contract shape or lock in a future start date. Minimal — inherit everything from the plan and defer the start date to activation: ```bash theme={null} curl -X POST https://api.alguna.io/subscriptions \ -H "Authorization: Bearer sk_live_..." \ -H "Alguna-Version: 2026-04-01" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "wcqYrqfE", "plan_id": "pln_032wMej82trlC5RulBsDJY" }' ``` With an explicit contract override — useful when the customer signs today but the subscription should start on a future date: ```bash theme={null} curl -X POST https://api.alguna.io/subscriptions \ -H "Authorization: Bearer sk_live_..." \ -H "Alguna-Version: 2026-04-01" \ -H "Content-Type: application/json" \ -d '{ "customer_id": "wcqYrqfE", "plan_id": "pln_032wMej82trlC5RulBsDJY", "contract": { "period_type": "fixed", "duration_months": 12, "start_date": "2026-07-01" } }' ``` ## Pattern 3: From a plan with per-customer overrides Send `plan_id` and `items` together. Each body item either: * Overrides a matching plan item (same `product_id` or `bundle_id`). The body's price definition fully replaces the plan item's price. * Appends a new item when nothing on the plan matches. This is the standard pattern for per-customer discounts or bespoke add-ons layered on top of a shared plan. ### 3a. Override a single product's price The plan has `prod_032wMej82trlC5RulBsDJY` at \$500/mo. This customer negotiated \$400/mo. ```json theme={null} { "customer_id": "AcBigCo12", "plan_id": "pln_032wMej82trlC5RulBsDJY", "items": [ { "product_id": "prod_032wMej82trlC5RulBsDJY", "price": { "type": "fixed", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "fixed_pricing_model": { "price_per_unit": "400.00", "units": 1 } } } ] } ``` All other plan items (metered API usage, data transfer, etc.) pass through unchanged. ### 3b. Append a custom add-on The plan has its standard item set. This customer also gets a dedicated support line item that is not on the plan. ```json theme={null} { "customer_id": "AcBigCo12", "plan_id": "pln_032wMej82trlC5RulBsDJY", "items": [ { "product_id": "prod_07fx2Nej82trlC5RulBsDJY", "price": { "type": "fixed", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "fixed_pricing_model": { "price_per_unit": "2500.00", "units": 1 } } } ] } ``` Because `prod_07fx2Nej82trlC5RulBsDJY` is not on the plan, it is appended to the materialized item set. Nothing else is touched. ## Pattern 4: With bundles Bundles group priced items that are billed as a unit. Reference a bundle with `bundle_id` inside `items`, and supply nested `items` for the children you want priced. ### 4a. Raw bundle (no plan) ```json theme={null} { "customer_id": "wcqYrqfE", "currency": "USD", "items": [ { "bundle_id": "bnd_032wMej82trlC5RulBsDJY", "items": [ { "product_id": "prod_032wMej82trlC5RulBsDJY", "price": { "type": "fixed", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "fixed_pricing_model": { "price_per_unit": "250.00", "units": 1 } } }, { "product_id": "prod_09tx7Nej82trlC5RulBsDJY", "price": { "type": "unit", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "unit_pricing_model": { "price_per_unit": "20.00" } } } ] } ] } ``` Every child under `items[].items[]` is a fully priced item. The API does not look up bundle defaults when children are provided inline, so supply the complete price definition for each child you want in the subscription. ### 4b. Override a bundle inside a plan The plan includes `bnd_032wMej82trlC5RulBsDJY`. For this customer, override the seats child to \$15 per seat. ```json theme={null} { "customer_id": "AcBigCo12", "plan_id": "pln_09uyMej82trlC5RulBsDJY", "items": [ { "bundle_id": "bnd_032wMej82trlC5RulBsDJY", "items": [ { "product_id": "prod_032wMej82trlC5RulBsDJY", "price": { "type": "fixed", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "fixed_pricing_model": { "price_per_unit": "250.00", "units": 1 } } }, { "product_id": "prod_09tx7Nej82trlC5RulBsDJY", "price": { "type": "unit", "billing_interval": "monthly", "fee_type": "fixed", "billing_direction": "arrears", "billing_frequency": "recurring", "unit_pricing_model": { "price_per_unit": "15.00" } } } ] } ] } ``` Overriding a bundle replaces the entire bundle item including every child. If you only need to adjust one child price after the subscription exists, use the changes API. See [Updating a Subscription](/docs/api-reference/v2/examples/updating-a-subscription). ## Response All patterns return the same `SubscriptionResponse` shape. Key fields on the initial response: * `id`: the subscription identifier (plain 8-char string, for example `CQCncgVu`). * `status`: `draft` on create, unless you passed `auto_activate: true`. * `current_version_id`: populated once the subscription is activated. * `pending_changes`: empty on create. * `created_at` and `updated_at`: RFC3339 timestamps (for example `2026-07-01T00:00:00Z`). To fetch the full materialized item set after activation, call [`get-current-subscription-version`](/docs/api-reference/v2/2026-04-01/subscription-versions/get-the-current-active-subscription-version) (`GET /subscriptions/{id}/versions/current`). For mutations after creation, see [Updating a Subscription](/docs/api-reference/v2/examples/updating-a-subscription).