Skip to main content
POST
/
subscriptions
Create a subscription
curl --request POST \
  --url https://api.alguna.io/subscriptions \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cust_abc123",
  "auto_activate": false,
  "billing": {
    "auto_issue_invoices": true,
    "auto_pay_invoices": false,
    "first_billing_date": "2026-07-01",
    "payment_terms": "net_30"
  },
  "contract": {
    "duration_months": 12,
    "period_type": "fixed",
    "start_date": "2026-07-01"
  },
  "currency": "USD",
  "items": [
    {
      "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"
        }
      ],
      "product_id": "prod_abc123"
    }
  ],
  "metadata": {},
  "name": "Acme Corp - Enterprise",
  "plan_id": "pln_abc123",
  "renewal": {
    "auto_renew": true,
    "duration_months": 12,
    "period_type": "fixed"
  }
}
'
{
  "billing": {
    "auto_issue_invoices": true,
    "auto_pay_invoices": false,
    "first_billing_date": "2026-01-01T00:00:00Z",
    "payment_terms": "net_30"
  },
  "contract": {
    "period_type": "fixed",
    "duration_months": 12,
    "end_date": "2027-01-01T00:00:00Z",
    "start_date": "2026-01-01T00:00:00Z"
  },
  "created_at": "2025-12-15T10:30:00Z",
  "currency": "USD",
  "customer_id": "cust_abc123",
  "id": "sub_abc123",
  "metadata": {},
  "name": "Acme Corp - Enterprise",
  "pending_changes": [
    {
      "status": "draft",
      "version_id": "subv_abc123",
      "description": "Q3 upgrade",
      "effective_at": "2027-01-01T00:00:00Z"
    }
  ],
  "renewal": {
    "auto_renew": true,
    "duration_months": 12,
    "period_type": "fixed"
  },
  "status": "active",
  "updated_at": "2026-04-04T10:00:05Z",
  "activated_at": "2026-01-01T00:00:00Z",
  "current_version_id": "subv_abc123",
  "discount": {
    "amount": "10",
    "duration_type": "fixed",
    "type": "percentage",
    "duration_unit": "months",
    "duration_value": 6
  },
  "maximum_spend": {
    "amount": "500.00",
    "period": "monthly"
  },
  "minimum_spend": {
    "amount": "500.00",
    "period": "monthly"
  },
  "plan_id": "pln_abc123",
  "price_escalation": {
    "enabled": true,
    "interval_months": 12,
    "type": "percentage",
    "escalate_metered_unit_rates": false,
    "percentage": "5.00"
  },
  "trial_period_days": 30
}

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
​
customer_id
string
required

Customer ID

Example:

"cust_abc123"

​
auto_activate
boolean | null

Auto-activate after creation

Example:

false

​
billing
object

Billing configuration

​
contract
object

Contract configuration

​
currency
string | null

Currency code. Required when plan_id is not provided. When plan_id is set, defaults to the customer's currency.

Example:

"USD"

​
items
object[]

Items for the first subscription version. Without plan_id, this is the full set of items. With plan_id, items override matching plan items (by product_id or bundle_id) and non-matching items are appended.

​
metadata
object

Key-value metadata

​
name
string | null

Subscription name

Example:

"Acme Corp - Enterprise"

​
plan_id
string | null

Plan ID to use as the base item set (optional)

Example:

"pln_abc123"

​
renewal
object

Renewal configuration

Response

Success

​
billing
object
required

Billing configuration

​
contract
object
required

Contract configuration

​
created_at
string<date-time>
required

When the subscription was created

Example:

"2025-12-15T10:30:00Z"

​
currency
string
required

ISO 4217 currency code

Example:

"USD"

​
customer_id
string
required

Customer ID

Example:

"cust_abc123"

​
id
string
required

Unique identifier

Example:

"sub_abc123"

​
metadata
object
required

Key-value metadata

​
name
string
required

Subscription name

Example:

"Acme Corp - Enterprise"

​
pending_changes
object[]
required

Pending version changes

​
renewal
object
required

Renewal configuration

​
status
string
required

Subscription status

Example:

"active"

​
updated_at
string<date-time>
required

When the subscription was last updated

Example:

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

​
activated_at
string<date-time> | null

When the subscription was activated

Example:

"2026-01-01T00:00:00Z"

​
current_version_id
string | null

Current active version ID

Example:

"subv_abc123"

​
discount
object

Subscription-level discount

​
maximum_spend
object

Maximum spend threshold

​
minimum_spend
object

Minimum spend threshold

​
plan_id
string | null

Plan ID

Example:

"pln_abc123"

​
price_escalation
object

Price escalation configuration

​
trial_period_days
integer<int64> | null

Trial period in days

Example:

30