Editing Subscriptions

Editing a subscription means one of two different things, and Alguna keeps them apart. Metadata edits (name, description, discount, spend thresholds, renewal and invoice flags, tags) apply immediately and do not touch what the customer is billed for. Pricing edits (adding, removing or re-pricing products) produce a new version that takes effect on a date you choose, with proration where it applies. Use this page to pick the right path; the walkthrough below covers the dashboard editor. See How Alguna Works for why the item set is versioned.

Which change is it?

You want to…	Path	Creates a version?
Rename, change description, tags or metadata	Dashboard Edit, or `PATCH /subscriptions/{id}`	No
Change subscription-level discount, minimum/maximum spend, trial, price escalation	Same as above	No
Change renewal (`auto_renew`, duration) or billing flags (auto-issue, auto-pay)	Same as above	No
Add, remove or re-price a product; swap plan; change tiers	Dashboard Edit → Products, or `POST /subscriptions/{id}/changes`	Yes — see Amendments
Build a full replacement item set and iterate before publishing	Dashboard versions, or `POST /subscriptions/{id}/versions`	Yes — see Versioning
Get the change signed by the customer	Amendment quote from the dashboard	Yes — see Amendments
End the subscription	Cancel	No

A draft subscription is different: nothing is live, so you can change anything freely, and delete it with DELETE /subscriptions/{id}.

Metadata edits via the API

PATCH /subscriptions/{id} patches only the fields you send. It never modifies the priced item set.

curl -X PATCH https://api.alguna.io/subscriptions/sub_abc123 \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp — Enterprise",
    "renewal": { "auto_renew": true, "period_type": "fixed", "duration_months": 12 },
    "discount": {
      "type": "percentage",
      "amount": "10",
      "duration_type": "fixed",
      "duration_value": 6,
      "duration_unit": "months"
    },
    "metadata": { "crm_opportunity_id": "006Xy000004abcd" }
  }'

import os

import requests

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

response = requests.patch(
    "https://api.alguna.io/subscriptions/sub_abc123",
    headers=HEADERS,
    json={
        "name": "Acme Corp — Enterprise",
        "renewal": {"auto_renew": True, "period_type": "fixed", "duration_months": 12},
        "discount": {
            "type": "percentage",
            "amount": "10",
            "duration_type": "fixed",
            "duration_value": 6,
            "duration_unit": "months",
        },
        "metadata": {"crm_opportunity_id": "006Xy000004abcd"},
    },
    timeout=10,
)
response.raise_for_status()

Subscription-level discounts are percentage only. To remove a metadata key, send it with a null value. A subscription.updated webhook fires on success.

Editing in the dashboard

Open the editor

On the Subscription Details page click Edit in the top-right corner.

Subscription Details page showing subscription and contract details, the products with their pricing, and the Edit button

Add products

In the Products section click Add Product, search, tick the products you want, and click Add Product(s). Set a price for each new line.

Remove products

Click the Delete icon on the line and confirm with Remove.

Subscription editor showing a product line with fee type, billing interval and pricing, and a Remove action

Change pricing

Adjust the amount, tiers or pricing model on any line. On an active subscription, pricing changes are collected into a new version rather than applied in place.

Choose when it takes effect

When you save changes to an active subscription you choose the version start:

From start of a billing cycle — the change lands on a cycle boundary. Nothing is prorated. Best for metered products and scheduled changes.
Mid-cycle — the change lands on the date you pick inside the current cycle and a prorated invoice is generated for the price difference. See Proration.

The valid dates for each mode come from the subscription’s billing schedule; the API exposes the same ranges through GET /subscriptions/{id}/billing-dates.

Add a note and save

Add a note describing the change; it is stored on the version as its description and shows in the version history. Click Save Changes.

Confirm changes dialog with an effective-from date and a notes field

If an approval rule matches the change, it waits for approval before it is published.

Next steps

Amendments

Add, remove and re-price products on an active subscription.

Versioning

How drafts, published versions and effective dates work.

Proration

What a mid-cycle change costs.

Updating a Subscription (API)

Request bodies for every kind of change.

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

Editing Subscriptions

Which change is it?

Metadata edits via the API

Editing in the dashboard

Next steps

Amendments

Versioning

Proration

Updating a Subscription (API)

​Which change is it?

​Metadata edits via the API

​Editing in the dashboard

​Next steps

Amendments

Versioning

Proration

Updating a Subscription (API)

Which change is it?

Metadata edits via the API

Editing in the dashboard

Next steps