Change a subscription's units

Sets the new total. The same classification as the Update Units dialog decides what happens: charged now on an invoice, deferred to the renewal invoice, or credited.

POST /v1/subscriptions/{id}/units

cURL

Increase, charged now

curl --request POST \
  --url https://api.saasybill.com/v1/subscriptions/{id}/units \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "units": 15,
  "prorate": true,
  "proration_behaviour": "charge_immediately",
  "effective_date": "2026-10-08"
}
'

200

Increase, charged now

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
  "customer_code": "ACME-001",
  "plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
  "status": "active",
  "currency": "AUD",
  "interval": {
    "unit": "month",
    "count": 1
  },
  "timezone": "Australia/Sydney",
  "start_date": "2026-09-30",
  "renewal_date": "2026-10-30",
  "end_date": null,
  "units": 15,
  "minimum_units": 5,
  "discount_percent": "10.00",
  "cancel_at_period_end": false,
  "end_after_cycles": null,
  "label": "Acme � Team plan",
  "invoice_reference": "PO-4471",
  "renewal_value": "162.0000",
  "usage_value": "0.0000",
  "usage_value_annual": "0.0000",
  "minimum_usage_value": "0.0000",
  "meters": [],
  "cpi_enabled": false,
  "created": "2026-09-30T04:12:00.000Z",
  "change": {
    "units": 15,
    "invoice": {
      "id": "6a9b4d0e-2c37-4f15-8d8a-7e3f1c5b9a01",
      "object": "invoice",
      "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
      "subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
      "number": "INV-0043",
      "reference": null,
      "status": "awaiting_approval",
      "currency": "AUD",
      "invoice_date": "2026-09-29T14:00:00.000Z",
      "due_date": "2026-10-29T13:00:00.000Z",
      "subtotal": "39.1900",
      "total": "43.1100",
      "credit_note_amount": "0.0000",
      "amount_paid": null,
      "sent": false,
      "xero": {
        "sync_status": "synced",
        "invoice_id": "f0e9d8c7-b6a5-4f43-9210-fedcba987654",
        "sync_error": null
      },
      "lines": [
        {
          "id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e99",
          "type": "subscription",
          "revenue_type": "new_subscription",
          "meter": null,
          "usage_quantity": null,
          "name": "Team",
          "description": "Team � 5 additional seats, prorated from 8 Oct 2026",
          "units": 5,
          "amount": "43.5500",
          "discount_amount": "4.3600",
          "charge_amount": "39.1900",
          "effective_date": "2026-10-07T13:00:00.000Z"
        }
      ],
      "created": "2026-09-30T04:12:01.000Z"
    },
    "renewal_invoice": null,
    "deferred_to_renewal": false,
    "credit_note": null,
    "document": null,
    "document_source": null,
    "document_fallback_reason": null
  }
}

Requires the subscriptions:write scope. See Authentication.

Authorizations

Authorization · string · header · required

An API key. Its scopes decide what it may call: customers:read (List and look up customers.) customers:write (Create customers, and Xero contacts where the organisation allows it.) catalogue:read (List plans and charges.) subscriptions:read (List and look up subscriptions.) subscriptions:write (Create subscriptions, change units, end and restore them.) invoices:read (List and look up invoices.) credit_notes:read (List and look up credit notes, and where their credit was applied.)

Headers

Idempotency-Key · string

1 to 255 printable characters. A retry with the same key and body returns the first response.

Required string length: 1 - 255

Example:

"signup_8f3a2c1d"

Path Parameters

id · string · required

The Saasybill id of the subscription.

Example:

"9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33"

Body

application/json

units · integer · required

The new total number of units, not a change.

Required range: 0 <= x <= 999999999

prorate · boolean

Charge or credit for the rest of the period. Default false.

proration_behaviour · enum<string>

Available options: charge_immediately, charge_on_renewal

effective_date · string

Required to prorate.

Pattern: ^\d{4}-\d{2}-\d{2}$

document · enum<string>

Only once the renewal invoice has been created: amend it, or bill the change on its own. Optional; when left out, your organisation's API setting decides (a separate invoice unless you chose Amend). Refused before the renewal invoice exists.

Available options: amend, separate

Response

200

application/json

Success.

id · string · required

object · string · required

Allowed value: "subscription"

customer · string · required

customer_code · string | null · required

plan · string · required

status · enum<string> · required

Available options: pending, active, complete, ended

currency · string · required

interval · object · required

Show child attributes

timezone · string · required

start_date · string · required

YYYY-MM-DD, in the subscription's own timezone.

renewal_date · string | null · required

YYYY-MM-DD, in the subscription's own timezone.

end_date · string | null · required

YYYY-MM-DD, in the subscription's own timezone.

units · integer · required

minimum_units · integer · required

discount_percent · string · required

A decimal string, e.g. "19.9900".

cancel_at_period_end · boolean · required

end_after_cycles · integer | null · required

label · string | null · required

invoice_reference · string | null · required

renewal_value · string · required

What the next period is certain to bill: the plan at its current units, the add-ons, and the minimum units of each meter the plan bills, net of the discount. Usage above the meter minimums is not included; see usage_value.

usage_value · string · required

The average, over the last three closed usage periods, of what each billed for usage above the meter minimums, net of the discount. An estimate at the plan's current meter prices, and never part of renewal_value. 0 until a usage period has closed, and for a plan that bills no meter.

usage_value_annual · string · required

usage_value times the periods in a year.

minimum_usage_value · string · required

The part of renewal_value that is the meter minimums, net of the discount. 0 for a plan that bills no meter.

meters · object[] · required

The meters the subscription's plan bills for, with the minimum each is billed at.

Show child attributes

cpi_enabled · boolean · required

Whether the price rises with CPI at each renewal.

created · string<date-time> · required

ISO 8601, UTC.

change · object · required

Show child attributes