Skip to main content
POST
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.) invoices:write (Bill a customer once for charges, without a subscription.) credit_notes:read (List and look up credit notes, and where their credit was applied.) usage:write (Send usage events, which are billed to the subscription they name.)

Scopes

subscriptions:write

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. When left out, your organisation's API proration settings decide (off unless you changed them); name it to override them.

proration_behaviour
enum<string>

Needs prorate: true. Defaults to charge_immediately.

Available options:
charge_immediately,
charge_on_renewal
effective_date
string

Needs proration. Required with prorate: true; when your settings prorate the change it defaults to today.

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

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

The units the subscription was set to. A period bills this or minimum_units, whichever is larger.

minimum_units
integer
required

The minimum units in force: the plan's, or the subscription's own when that is higher. A period bills at least this many units. A change to the subscription's own minimum starts with the next renewal.

discount_percent
string
required

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

cancel_at_period_end
boolean
required
end_after_cycles
integer | null
required
contract_start_date
string | null
required

The day the subscription's contract term starts, YYYY-MM-DD. A record only: it changes nothing about billing. Null when none is recorded.

contract_end_date
string | null
required

The last day of the subscription's contract term, YYYY-MM-DD. A record only: it does not end the subscription or change billing (see end_after_cycles). Null when none is recorded.

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.

cpi_enabled
boolean
required

Whether the price rises with CPI at each renewal.

created
string<date-time>
required

ISO 8601, UTC.

change
object
required