Skip to main content
POST
/
plans
Create a plan
curl --request POST \
  --url https://api.alguna.io/plans \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "currency": "USD",
  "name": "Enterprise Plan",
  "additional_terms": "<string>",
  "auto_activate": false,
  "auto_renew": true,
  "contract_duration": 12,
  "contract_period_type": "fixed",
  "description": "Full-featured enterprise plan",
  "entitlements": [
    {
      "entitlement_key": "api_access",
      "mode": "static",
      "type": "boolean",
      "value": "true"
    }
  ],
  "invoice_settings": {
    "auto_issue_invoices": true,
    "auto_pay_invoices": false,
    "invoice_footer_text": "Questions? support@example.com",
    "invoice_memo_template": "Thanks for your business",
    "send_activation_email": true,
    "send_invoices_to_customer": true,
    "send_receipts_to_customer": true
  },
  "items": [
    {
      "bundle_description": "Premium support and SSO",
      "bundle_id": "bun_abc123",
      "items": [
        {
          "price": {
            "billing_direction": "arrears",
            "billing_interval": "monthly",
            "fee_type": "fixed",
            "type": "fixed",
            "billing_frequency": "recurring",
            "charge_on_contract_start": false,
            "display_order": 1,
            "metric_ids": [
              "<string>"
            ],
            "trial_period_days": 30
          },
          "product_id": "prod_abc123"
        }
      ],
      "name": "Enterprise Add-ons",
      "product_id": "prod_abc123"
    }
  ],
  "payment_terms": "net_30",
  "renewal_duration": 12,
  "renewal_period_type": "fixed",
  "tags": [
    "tag_abc123"
  ],
  "trial_period_days": 14
}
'
{
  "created_at": "2026-04-01T10:00:00Z",
  "currency": "USD",
  "id": "pln_01H1VECT",
  "name": "Enterprise Plan",
  "updated_at": "2026-04-01T12:30:00Z",
  "description": "Full-featured enterprise plan"
}

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.

Authorizations

​
Authorization
string
header
required

API key authentication. Pass your API key as a Bearer token.

Headers

​
Alguna-Version
enum<string>
required
Available options:
2026-04-01
​
Idempotency-Key
string

A unique string used to ensure the request is processed exactly once. If you retry a request with the same idempotency key within 24 hours, the original response is returned without re-executing the operation.

Maximum string length: 255
Example:

"ik_a1b2c3d4e5f6"

Body

application/json
​
currency
string
required

ISO 4217 currency code

Example:

"USD"

​
name
string
required

Plan name

Example:

"Enterprise Plan"

​
additional_terms
string | null

Markdown additional terms appended to the contract

​
auto_activate
boolean | null

Auto-activate subscriptions created from this plan

Example:

false

​
auto_renew
boolean | null

Whether the plan auto-renews

Example:

true

​
contract_duration
integer<int64> | null

Contract duration in months

Example:

12

​
contract_period_type
enum<string> | null

Contract period type

Available options:
fixed,
monthly_rolling
Example:

"fixed"

​
description
string

Plan description

Example:

"Full-featured enterprise plan"

​
discount
object

Plan-level discount applied across the price set

​
entitlements
object[]

Entitlement configs to provision with the plan

​
invoice_settings
object

Invoice/email behavior overrides for the plan

​
items
object[]

Items that make up the plan's pricing template. Each item is either a standalone product (product_id + price) or a bundle (bundle_id + name + items).

​
maximum_spend
object

Maximum spend per period

​
minimum_spend
object

Minimum spend per period

​
payment_terms
string | null

Invoice payment terms

Example:

"net_30"

​
price_escalation
object

Price escalation config

​
renewal_duration
integer<int64> | null

Renewal duration in months

Example:

12

​
renewal_period_type
enum<string> | null

Renewal period type

Available options:
fixed,
monthly_rolling
​
tags
string[]

Tag IDs to associate with the plan

Example:
["tag_abc123"]
​
trial_period_days
integer<int64> | null

Trial period in days

Example:

14

Response

Success

​
created_at
string<date-time>
required

Timestamp when the plan was created

Example:

"2026-04-01T10:00:00Z"

​
currency
string
required

The currency in which the plan is billed

Example:

"USD"

​
id
string
required

Unique identifier for the plan

Example:

"pln_01H1VECT"

​
name
string
required

The name of the plan

Example:

"Enterprise Plan"

​
updated_at
string<date-time>
required

Timestamp when the plan was last updated

Example:

"2026-04-01T12:30:00Z"

​
description
string | null

A brief description of the plan

Example:

"Full-featured enterprise plan"