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 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.
• At least one product reference (prod_...) on each item, or a bundle reference (bnd_...) when using bundle items. See create-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 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

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.

{
  "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 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:

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:

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.

{
  "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.

{
  "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)

{
  "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.

{
  "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.

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 (GET /subscriptions/{id}/versions/current).

For mutations after creation, see Updating a Subscription.