Subscription Amendments

An amendment is a mid-term commercial change to an active subscription: an upgrade, extra seats, an added product, a removed add-on, a renegotiated rate, a plan swap. In Alguna an amendment is expressed as a delta (add, remove, update) against the current version, with an effective timing; Alguna computes the resulting version, prorates advance charges where the timing is mid-cycle, and keeps the previous version as history. Use this page for what to change and when; Versioning explains the underlying draft/published model and Proration the money. See How Alguna Works for why changes are versioned rather than overwritten.

What you can amend

Change	How it is expressed	Proration
Add a product or bundle	`add`	Prorated charge if mid-cycle
Remove a product or bundle	`remove`	Prorated credit if mid-cycle
Change quantity or rate on a product	`update` with `adjust` (partial)	Prorated difference if mid-cycle
Replace a price entirely (new type, new tiers)	`update` with `new_price`	Prorated difference if mid-cycle
Switch to a different plan	`plan_id`	Prorated difference if mid-cycle
Change bundle contents	`update` with `add_items` / `remove_items` / `items`	As above, per child

Proration only ever applies to advance fixed-class charges; metered and arrears charges are never prorated. Contract dates, renewal terms, discount and spend thresholds are not amendments: they change through PATCH /subscriptions/{id} with no new version. See Editing Subscriptions for the full decision table.

Choose when it takes effect

The effective field (dashboard: the version start) accepts a keyword or a date:

Value	Meaning	Use for
`immediate`	Now. Advance charges are prorated for the rest of the cycle.	Urgent upgrades, add-ons the customer needs today
`next_billing_period`	Start of the next invoicing cycle. No proration.	Downgrades, removals, metered changes
`next_term_renewal`	End of the current contract term. No proration.	Renewal repricing
`YYYY-MM-DD` or RFC 3339 timestamp	A specific date or moment	Scheduled changes

GET /subscriptions/{id}/billing-dates returns the dates that are valid for on-cycle and mid-cycle changes.

Preview before you commit

POST /subscriptions/{id}/changes/preview takes the same body as the apply endpoint and returns what would change (changes_applied with added, removed and updated item refs, and the effective_at it resolves to) without writing anything. Use it to confirm the delta resolves as you expect, or to drive an approval step, before applying. In the dashboard the same information is shown on the save dialog.

Apply an amendment

POST /subscriptions/{id}/changes computes the new version and publishes it, unless you pass draft: true. This example adds 25 seats to a per-seat product and adds a support add-on, effective immediately:

curl -X POST https://api.alguna.io/subscriptions/sub_abc123/changes \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "update": [
      {
        "product_id": "prod_seats",
        "adjust": { "fixed_pricing_model": { "units": 50 } }
      }
    ],
    "add": [
      {
        "product_id": "prod_support",
        "new_price": {
          "type": "fixed",
          "fee_type": "fixed",
          "billing_direction": "advance",
          "billing_frequency": "recurring",
          "billing_interval": "monthly",
          "fixed_pricing_model": { "price_per_unit": "250.00", "units": 1 }
        }
      }
    ],
    "effective": "immediate",
    "description": "Expansion: 25 → 50 seats, premium support"
  }'

import os

import requests

HEADERS = {
    "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
    "Alguna-Version": "2026-04-01",
    "Content-Type": "application/json",
}

change = {
    "update": [
        {"product_id": "prod_seats", "adjust": {"fixed_pricing_model": {"units": 50}}}
    ],
    "add": [
        {
            "product_id": "prod_support",
            "new_price": {
                "type": "fixed",
                "fee_type": "fixed",
                "billing_direction": "advance",
                "billing_frequency": "recurring",
                "billing_interval": "monthly",
                "fixed_pricing_model": {"price_per_unit": "250.00", "units": 1},
            },
        }
    ],
    "effective": "immediate",
    "description": "Expansion: 25 → 50 seats, premium support",
}

base = "https://api.alguna.io/subscriptions/sub_abc123/changes"

preview = requests.post(f"{base}/preview", headers=HEADERS, json=change, timeout=10)
preview.raise_for_status()
print("would apply:", preview.json()["changes_applied"])

applied = requests.post(base, headers=HEADERS, json=change, timeout=10)
applied.raise_for_status()
result = applied.json()
print(result["version_id"], result["version_status"], result.get("effective_at"))

The response carries the new version_id, its version_status (draft or published), the source_version_id the delta was computed against, and is_new_version (false when an existing draft was replaced instead). Request bodies for plan swaps, tier replacement and bundle operations are in Updating a Subscription.

In the dashboard

Open the subscription and click Edit.
Add, remove or re-price products in the Products section.
Save, and choose the version start: From start of a billing cycle (no proration) or Mid-cycle (a prorated invoice for the difference).
Add a note describing why, and confirm.

The step-by-step is in Editing Subscriptions.

Common scenarios

Upgrade mid-cycle — update the product’s price (or send plan_id for the higher plan) with effective: "immediate". The customer is charged the prorated difference for the rest of the cycle. Add seats — update with adjust: { "fixed_pricing_model": { "units": <new count> } }. Mid-cycle, the extra seats are prorated; on next_billing_period, the full new count bills from the next cycle. Remove an add-on without issuing a credit — remove with effective: "next_billing_period". The add-on bills through the end of the current cycle and stops. Renewal repricing — update the affected prices with effective: "next_term_renewal". Nothing changes until the contract rolls over. For a percentage uplift every year, set price_escalation on the subscription instead. Negotiated discount — a subscription-wide discount is metadata, not an amendment: PATCH /subscriptions/{id} with discount. A discount on one product goes on that product’s price through update.

Approvals

If an approval rule matches the change (a discount above a threshold, a specific product, a non-standard term), the amendment waits in Pending approval until an approver acts. Approved amendments publish on their effective date; rejected ones are returned for editing. Track them under Approvals in the dashboard.

Getting an amendment signed

For sales-led contracts the customer often needs to sign the change. From the dashboard, stage the amendment as a draft version and issue it as an amendment quote: the customer receives a signing link exactly as for a new deal (Sending Quotes). When they sign, the staged version is published and takes effect on its date. Only one amendment quote can be open on a subscription at a time. Quotes are dashboard-only; there is no public API for issuing them.

Audit trail

Every amendment is a version with a description, so the history of what changed and when is the version list: GET /subscriptions/{id}/versions. A subscription.version.updated webhook fires each time a version is created, replaced or published.

Next steps

Proration

Exactly how a mid-cycle amendment is priced.

Versioning

Drafts, published versions and effective dates.

Updating a Subscription (API)

Every request body: adjust, replace, swap, bundles.

Entitlements

Update what the customer can access along with what they pay.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

Subscription Amendments

What you can amend

Choose when it takes effect

Preview before you commit

Apply an amendment

In the dashboard

Common scenarios

Approvals

Getting an amendment signed

Audit trail

Next steps

Proration

Versioning

Updating a Subscription (API)

Entitlements

​What you can amend

​Choose when it takes effect

​Preview before you commit

​Apply an amendment

​In the dashboard

​Common scenarios

​Approvals

​Getting an amendment signed

​Audit trail

​Next steps

Proration

Versioning

Updating a Subscription (API)

Entitlements

What you can amend

Choose when it takes effect

Preview before you commit

Apply an amendment

In the dashboard

Common scenarios

Approvals

Getting an amendment signed

Audit trail

Next steps