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
when
enum<string>
required
Available options:
now,
period_end
delete_unsent_invoices
boolean

With when: now: also delete the subscription's invoices that were never sent, in Xero. Default false.

void_approved_invoices
boolean

With when: now: also void its approved, unpaid invoices in Xero. Default false.

invoice_usage_now
boolean

With when: now: raise the final usage invoice at once instead of after the organisation's usage grace period. Ignored when the plan bills no meter. Default false.

deferred_items
enum<string>

What to do with the subscription's deferred line items, which wait for a renewal invoice that will not happen. invoice_now raises an invoice for them, invoice_at_period_end (only with when: period_end) raises it on the end date, discard deletes them. Ignored when there are none. When left out, the organisation's Deferred Items on End setting decides: by default they are neither invoiced nor deleted and the subscription shows an attention prompt in Saasybill until someone chooses.

Available options:
invoice_now,
invoice_at_period_end,
discard

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.