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 applies the same rules as the Update Units dialog in the app. You choose whether to prorate, or leave it out and let the organisation’s proration defaults decide. The plan type and the direction of the change decide the document.

Units are for a plan’s recurring fee. A plan with no recurring fee (no_base_fee) has no units, and the request is refused. Metered usage isn’t set as units. Report it as events instead.

Request fields

Field	Type	Description
`units`	integer	Required. The new total number of units.
`prorate`	boolean	Charge or credit for the rest of the current period. When you leave it out, the organisation’s proration defaults decide, and they don’t prorate unless an admin has switched them on. Send it to override them.
`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. When a proration default prorates the change, it defaults to today.
`document`	string	`amend` or `separate`. Used only after the renewal invoice is created. Optional: when you leave it out, the organisation’s setting decides.

proration_behaviour is refused unless prorate is true. effective_date is refused when the change isn’t prorated.

units can be lower than the subscription’s minimum. See Minimum units.

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`.
`prorate` left out	The proration defaults decide which of the rows above applies.	`change.proration_source` is `organisation_default`.

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

The subscription’s units update straight away, but the customer has paid for the period. What happens next depends on prorate.

You send	What happens	In the response
`prorate: true`	A prorated credit note is raised for the units removed, from the effective date to the next renewal. It is issued immediately and held as a credit balance on the subscription. `proration_behaviour` is fixed to `charge_immediately`.	`change.credit_note` holds its id.
`prorate: false`	No document is raised. The lower amount is billed from the next renewal.	`change.credit_note` is `null`.
`prorate` left out	The proration defaults decide.	`change.proration_source` is `organisation_default`.

A credit only covers units that were paid for. Units already removed without a credit aren’t credited again.

If you decrease units without prorating, proration is unavailable for further decreases until the next renewal.

Volume plans

On a volume plan, a unit change that crosses into another band re-prices every unit, so the total can move the opposite way to the units. An increase that crosses into a cheaper band lowers the total. Saasybill raises a prorated credit note instead of an invoice.

prorate can’t be false for this change. It answers 422 proration_required. When you leave prorate out, Saasybill prorates the change whatever the proration defaults say.
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.

A decrease that crosses into a dearer band raises the total. It is a charge, so the upgrade rules apply: proration is optional, and the upgrade default decides it when you leave prorate out.

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 renewal invoice has already been created, because there is no renewal invoice left to add to

Minimum units

A minimum is a billing floor, not a limit on units. You can set units below the subscription’s minimum, including to 0. Each period bills the larger of units and minimum_units. minimum_units on the subscription is the minimum in force: the plan’s, or the subscription’s own when that is higher. units stays what you set.

You send	What happens
`units` below `minimum_units`	`units` updates. The period still bills `minimum_units`, so nothing changes in what the customer pays.
`units` above `minimum_units`	The subscription bills `units`, with the usual proration rules.
A change that crosses the minimum	Only the part above the minimum is charged or credited.

For example, a subscription has a minimum of 10 units and is paid for 15.

Prorating a decrease to 6 credits only the 5 units between 15 and 10. The drop from 10 to 6 changes units and credits nothing.
Setting 6 and later prorating an increase to 15 charges only the 5 units between 10 and 15.
Moving from 8 to 5 changes units and raises no document. The period already bills the minimum.

A change that costs nothing extra has nothing to prorate. Naming prorate: true for it is refused with 422 proration_not_available. Send prorate: false, or leave prorate out. units_unchanged compares your total with units, not with the minimum.

You can’t change a subscription’s own minimum through the API after it is created. A new subscription takes minimum_units at creation. See Create a subscription.

Proration defaults

When a request leaves prorate out, the organisation’s proration defaults decide whether to prorate. They are off unless an admin switches them on, so an integration that never sends prorate behaves as it always has. An owner or admin can change them under Developer Settings, then Configuration. The setting is called Proration Behaviour. It has two parts.

Setting	Options	Applies to
Upgrades	Not prorated, Prorated, charged immediately or Prorated, charged at renewal	A change that charges: every increase, and a decrease on a volume plan that moves into a dearer band.
Downgrades	Not prorated or Prorated, credited immediately	A decrease that credits. The credit note is always issued immediately, so there is no timing to choose.

The rules:

A prorate in the request always wins. It is checked exactly as it always was, and the defaults aren’t consulted.
The outcome picks the setting, not the direction. A change that charges follows Upgrades. A credit you could decline follows Downgrades.
A default prorates from today. effective_date defaults to today in the subscription’s timezone. You can still send effective_date to choose another day in the current period.
A default yields instead of refusing. If the change can’t be prorated, the default doesn’t prorate and the request goes through. That is when there is nothing to prorate, when a non-prorated change has already locked proration for the period, or when the timing is fixed. A volume increase that lowers the total is credited immediately whatever the settings say.
A change left unprorated counts as non-prorated. It locks proration in that direction until the next renewal, exactly as prorate: false would.
Fields that contradict the outcome are still refused. proration_behaviour without prorate: true is refused whatever the settings say. So is effective_date when the defaults leave the change unprorated, with 422 effective_date_not_applicable.

The response says what happened. change.proration_source is organisation_default when the settings decided, and change.prorated says whether the change was prorated.

The defaults apply to API requests only. The Update Units dialog in the app always asks.

A sandbox copies the setting when you copy settings to it. See Testing.

After the renewal invoice is created

Saasybill creates a renewal invoice ahead of the renewal date, set by Invoice Creation Date 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. Then a document has to carry the change. You choose it per request with document, or once for the organisation.

`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.

Before the renewal invoice exists, document is refused. After it exists, document is optional.

Set a default for the organisation

Amending changes a document the customer may already hold, so the default is separate. An owner or admin can change it under Developer Settings, then Configuration. The setting is called Changes After Invoicing.

Setting	What a request without `document` does
Raise a separate invoice	Bills the change on its own. This is the default.
Amend the renewal invoice	Updates the renewal invoice.

A document in the request always wins over the setting.

If the setting is Amend and the renewal invoice can no longer be changed, for example because it has a payment or credit on it, Saasybill raises a separate invoice instead. It doesn’t refuse the request. The response says so in change.document_fallback_reason. A request that names amend itself is refused in that case, and the error says why.

A sandbox copies the setting when you copy settings to it. See Testing.

{
  "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. change.document tells you which happened.

The response

The response is the updated subscription with a change object.

`change` field	Description
`units`	The new total, as you set it. The subscription bills this or its `minimum_units`, whichever is larger.
`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.
`prorated`	`true` when the change was prorated.
`proration_behaviour`	`charge_immediately` or `charge_on_renewal` when the change was prorated. Otherwise `null`.
`effective_date`	`YYYY-MM-DD`. The day a prorated change took effect. Otherwise `null`.
`proration_source`	`request` when you named `prorate`, or `organisation_default` when the proration defaults decided, even if they decided not to prorate.
`document`	`amend` or `separate`: where the change went once the renewal invoice exists. `null` before then.
`document_source`	`request` when you named `document`, or `organisation_default` when the setting chose it. `null` before the renewal invoice exists.
`document_fallback_reason`	Set when the setting is Amend but the change was billed separately. The reason. Otherwise `null`.
`credit_note`	The id of the credit note raised, or `null`.

Charged now
Charged at renewal
Prorated by default
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,
    "prorated": true,
    "proration_behaviour": "charge_immediately",
    "effective_date": "2026-10-08",
    "proration_source": "request"
  }
}

{
  "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,
    "prorated": true,
    "proration_behaviour": "charge_on_renewal",
    "effective_date": "2026-10-08",
    "proration_source": "request"
  }
}

A request with no prorate, on an organisation whose Downgrades setting is Prorated, credited immediately.

{
  "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": "c41f7e92-6b0a-4d35-9a18-0f2e8d5b7c64",
    "prorated": true,
    "proration_behaviour": "charge_immediately",
    "effective_date": "2026-10-08",
    "proration_source": "organisation_default"
  }
}

{
  "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,
    "prorated": false,
    "proration_behaviour": null,
    "effective_date": null,
    "proration_source": "organisation_default"
  }
}

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

Example

curl https://api.saasybill.com/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://api.saasybill.com/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://api.saasybill.com/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` 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`
`effective_date` is sent for a change that isn’t prorated.	`effective_date_not_applicable`
`prorate` is `true` for a change with nothing to prorate, or after a non-prorated change locked proration.	`proration_not_available`

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

Credit notes

Usage

Request fields

What happens

Increasing units

Decreasing units

Volume plans

Units already paid for

When proration is fixed

Minimum units

Proration defaults

After the renewal invoice is created

Set a default for the organisation

The response

Example

When a change is refused