Change units

This page covers the API. For the billing logic behind it, see Billing changes. For the same change in the app, see Subscriptions.

POST /v1/subscriptions/{id}/units sets a subscription’s unit count. It needs the subscriptions:write scope. Send the new total, not the difference. Saasybill decides what the change costs and where to bill it, using the same rules as the Update Units dialog in the app. You choose whether to prorate.

Request fields

Field	Type	Description
`units`	integer	Required. The new total number of units.
`prorate`	boolean	Charge for the rest of the current period. Defaults to `false`.
`proration_behaviour`	string	With `prorate: true`. `charge_immediately` (the default) or `charge_on_renewal`.
`effective_date`	string	`YYYY-MM-DD`. Required with `prorate: true`. Must fall within the current billing period.
`document`	string	`amend` or `separate`. Required only inside the invoice window.

proration_behaviour and effective_date are refused unless prorate is true.

What happens

Saasybill classifies the new total against the units already paid for this period.

Increasing units

You send	What happens	In the response
`prorate: true`, `charge_immediately`	A prorated invoice is raised now for the extra units, from the effective date to the next renewal. It joins the subscription’s draft invoice if there is one.	`change.invoice` is set.
`prorate: true`, `charge_on_renewal`	The prorated amount is added as a line to the renewal invoice.	`change.deferred_to_renewal` is `true`.
`prorate: false`	The subscription’s `units` update straight away, but the extra units are billed in full at the next renewal. No document is raised now.	`change.invoice` is `null`.

Prorated amounts follow the proration formula: the difference in value, multiplied by the days remaining, divided by the days in the period.

If you increase units without prorating, proration is unavailable for further increases until the next renewal. A prorated request in that state is refused with 422.

Decreasing units

A decrease never raises a document. The subscription’s units update straight away, but the customer has paid for the period, so the lower amount is billed from the next renewal. Send prorate: false, or omit it.

Volume plans

On a volume plan, a unit increase that crosses into a cheaper band re-prices every unit, and the total can fall. Saasybill raises a prorated credit note instead of an invoice.

prorate can’t be false for this change. It answers 422 proration_required.
The credit is always issued immediately, so proration_behaviour is fixed to charge_immediately.
The credit note is held as a credit balance on the subscription and applied to future invoices. change.credit_note holds its id.

Units already paid for

Units at or below the number already paid for this period are never charged twice. If a customer drops from 10 to 8 units and then returns to 10, nothing more is billed until renewal.

When proration is fixed

proration_behaviour is fixed to charge_immediately when:

the subscription is in its final period, because there is no renewal to charge at
the next period has already been invoiced, because there is no renewal invoice left to add to

Inside the invoice window

Saasybill raises a renewal invoice ahead of the renewal date, set by Invoice Create Days in Company Settings. Once that has happened, a unit change touches two periods: the current one, and the next one that’s already been invoiced. In this window you must say which document carries the change.

`document`	What happens
`amend`	The renewal invoice is updated. Its plan line is re-priced at the new units, and the current period’s prorated charge is added to it.
`separate`	The change is billed on its own invoice. The renewal invoice isn’t touched.

Amending changes a document the customer may already hold, so the API never assumes it. Outside the window, document is refused. Inside it, document is required. The error names the choices when yours isn’t valid. Amending isn’t offered when the renewal invoice can’t be changed, for example after an earlier change was billed separately. The error message says so.

{
  "units": 15,
  "prorate": true,
  "effective_date": "2026-10-08",
  "document": "amend"
}

With amend, change.renewal_invoice is the updated renewal invoice. With separate, change.invoice is the new invoice.

The response

The response is the updated subscription with a change object.

`change` field	Description
`units`	The new total.
`invoice`	The invoice raised or updated by this change, or `null`.
`renewal_invoice`	The renewal invoice that was amended, or `null`.
`deferred_to_renewal`	`true` when the prorated amount was added to the next renewal invoice.
`credit_note`	The id of the credit note raised, or `null`.

Charged now
Charged at renewal
No document

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "units": 15,
  "renewal_value": "162.0000",
  "change": {
    "units": 15,
    "invoice": { "id": "6a9b4d0e-2c37-4f15-8d8a-7e3f1c5b9a01", "number": "INV-0043", "total": "43.1100", "…": "…" },
    "renewal_invoice": null,
    "deferred_to_renewal": false,
    "credit_note": null
  }
}

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "units": 15,
  "renewal_value": "162.0000",
  "change": {
    "units": 15,
    "invoice": null,
    "renewal_invoice": null,
    "deferred_to_renewal": true,
    "credit_note": null
  }
}

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "units": 8,
  "renewal_value": "86.4000",
  "change": {
    "units": 8,
    "invoice": null,
    "renewal_invoice": null,
    "deferred_to_renewal": false,
    "credit_note": null
  }
}

renewal_value in the response is what the next renewal will bill at the new units.

Example

curl https://app.saasybill.com/api/v1/subscriptions/9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33/units \
  -H "Authorization: Bearer $SAASYBILL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: seats_acme_2026-10-08_15" \
  -d '{
    "units": 15,
    "prorate": true,
    "proration_behaviour": "charge_immediately",
    "effective_date": "2026-10-08"
  }'

const response = await fetch(
  `https://app.saasybill.com/api/v1/subscriptions/${subscriptionId}/units`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.SAASYBILL_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": `seats_${accountId}_${changeId}`,
    },
    body: JSON.stringify({
      units: 15,
      prorate: true,
      proration_behaviour: "charge_immediately",
      effective_date: "2026-10-08",
    }),
  },
);

response = requests.post(
    f"https://app.saasybill.com/api/v1/subscriptions/{subscription_id}/units",
    headers={
        "Authorization": f"Bearer {os.environ['SAASYBILL_API_KEY']}",
        "Idempotency-Key": f"seats_{account_id}_{change_id}",
    },
    json={
        "units": 15,
        "prorate": True,
        "proration_behaviour": "charge_immediately",
        "effective_date": "2026-10-08",
    },
)

Send an Idempotency-Key built from your own change event. The key is optional here, but a retried seat change without one could be applied twice.

When a change is refused

A unit change is refused with 422 when it breaks a rule. See the unit change codes for each.

Rule	Code
The organisation is in Setup Mode.	`setup_mode_on`
The subscription has ended or completed.	`subscription_not_changeable`
The plan is a flat fee plan, which has no units.	`plan_has_no_units`
`units` is below the minimum.	`units_below_minimum`
`units` matches the current total.	`units_unchanged`
`prorate` is `true` without `effective_date`.	`effective_date_required`
`effective_date` is outside the current period.	`effective_date_out_of_period`

If your platform sends the current total on every sync, treat units_unchanged as success. The subscription already has the units you wanted.

A 409 xero_accounts_not_mapped means an admin needs to map the Xero accounts on the Integrations tab before units can change.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Request fields

What happens

Increasing units

Decreasing units

Volume plans

Units already paid for

When proration is fixed

Inside the invoice window

The response

Example

When a change is refused

​Request fields

​What happens

​Increasing units

​Decreasing units

​Volume plans

​Units already paid for

​When proration is fixed

​Inside the invoice window

​The response

​Example

​When a change is refused

Request fields

What happens

Increasing units

Decreasing units

Volume plans

Units already paid for

When proration is fixed

Inside the invoice window

The response

Example

When a change is refused