Cancel a subscription

Schedules a cancellation for a subscription. The effective timing can be a keyword (e.g. immediate, end_of_term) or a specific date. A cancellation reason code is required and a free-text note is optional.

POST /subscriptions/{id}/cancel

Cancel a subscription

cURL

curl --request POST \
  --url https://api.alguna.io/subscriptions/{id}/cancel \
  --header 'Alguna-Version: <alguna-version>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "no_longer_required",
  "effective": "end_of_term",
  "reason_description": "Customer is consolidating vendors"
}
'

200

{
  "assignments": [
    {
      "type": "owner",
      "user_id": "usr_abc123"
    }
  ],
  "billing": {
    "auto_issue_invoices": true,
    "auto_pay_invoices": false,
    "payment_collection_method": "autopay",
    "autopay_timing": "on_due_date",
    "first_billing_date": "2026-01-01T00:00:00Z",
    "payment_method_id": "pm_01H1VECT",
    "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",
    "billing_direction": "arrears"
  },
  "minimum_spend": {
    "amount": "500.00",
    "period": "monthly",
    "billing_direction": "arrears"
  },
  "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
}

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 that makes a retried write safe. If you send the same request with the same key within 24 hours, the API returns the stored response and does not run the request again. A 5xx or 429 response is not stored, so a retry with that key runs the request again.

Maximum string length: 255

Example:

"ik_a1b2c3d4e5f6"

Path Parameters

id · string · required

Unique identifier for the subscription

Body

application/json

reason · enum<string> · required

Cancellation reason

Available options: no_longer_required, moving_provider, pricing, support, features, upgraded, other

Example:

"no_longer_required"

effective · string | null

When cancellation takes effect

Example:

"end_of_term"

reason_description · string | null

Additional context for the cancellation

Example:

"Customer is consolidating vendors"

Response

200

application/json

Success

assignments · object[] · required

Users assigned to the subscription, such as its owner

Show child attributes

billing · object · required

Billing configuration

Show child attributes

contract · object · required

Contract configuration

Show child attributes

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

Show child attributes

renewal · object · required

Renewal configuration

Show child attributes

status · enum<string> · required

Subscription status

Available options: draft, active, canceled, approved

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 | null

Subscription-level discount

Show child attributes

maximum_spend · object | null

Maximum spend threshold

Show child attributes

minimum_spend · object | null

Minimum spend threshold

Show child attributes

plan_id · string | null

Plan ID

Example:

"pln_abc123"

price_escalation · object | null

Price escalation configuration

Show child attributes

trial_period_days · integer<int64> | null

Trial period in days

Example:

30