Skip to main content
PATCH
/
subscriptions
/
{id}
Update a subscription
curl --request PATCH \
  --url https://api.alguna.io/subscriptions/{id} \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "billing": {
    "auto_issue_invoices": true,
    "auto_pay_invoices": false,
    "first_billing_date": "2026-07-01",
    "payment_terms": "net_30"
  },
  "description": "Annual enterprise subscription",
  "metadata": {},
  "name": "Acme Corp - Enterprise",
  "renewal": {
    "auto_renew": true,
    "duration_months": 12,
    "period_type": "fixed"
  },
  "tags": [
    "tag_abc123"
  ],
  "trial_period_days": 30
}
'
{
  "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"

Path Parameters

​
id
string
required

Unique identifier for the subscription

Body

application/json
​
billing
object

Billing configuration

​
description
string | null

Description

Example:

"Annual enterprise subscription"

​
discount
object

Subscription-level discount (percentage only)

​
maximum_spend
object

Maximum spend threshold

​
metadata
object

Key-value metadata (null value removes key)

​
minimum_spend
object

Minimum spend threshold

​
name
string | null

Subscription name

Example:

"Acme Corp - Enterprise"

​
price_escalation
object

Price escalation config

​
renewal
object

Renewal configuration

​
tags
string[]

Tag IDs

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

Trial period in days

Example:

30

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