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
required

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"

Body

application/json
customer
string

The Saasybill customer id. Give this or customer_code.

Required string length: 1 - 100
customer_code
string

The organisation's own reference for the customer. Unique per organisation.

create_customer
object

Create the customer in Xero if no customer has customer_code. Needs the organisation to have allowed it.

plan
string

The plan id. Give this or plan_code.

Required string length: 1 - 100
plan_code
string
Required string length: 1 - 100
units
integer

Not for a plan with no units: a flat fee plan, or one with no recurring fee.

Required range: 0 <= x <= 999999999
flat_fee_price

Only where the plan allows its price to be overridden.

Required string length: 1 - 20
start_date
string

Defaults to today in the organisation's timezone.

Pattern: ^\d{4}-\d{2}-\d{2}$
end_after_cycles
integer | null
Required range: 1 <= x <= 1000
contract_start_date
string | null

The day the contract's term starts. A record only: it changes nothing about billing.

Pattern: ^d{4}-d{2}-d{2}$
contract_end_date
string | null

The last day of the contract's term, not before contract_start_date. A record only: it does not end the subscription (use end_after_cycles for that).

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

0 to 100. Defaults to 0.

Required string length: 1 - 20
label
string | null
Maximum string length: 255
invoice_reference
string | null
Maximum string length: 255
minimum_units
integer | null
Required range: 0 <= x <= 999999999
minimum_invoice_amount
Required string length: 1 - 20
invoice_due_days
integer | null
Required range: 1 <= x <= 365
meter_minimums
object[]

Raise the minimum of meters the plan bills, for this subscription only. A meter the plan does not bill is refused, and a meter named twice.

Maximum array length: 50
cpi_enabled
boolean

Raise the plan price, and the rates of any meters the plan bills, by the consumer price index at each renewal. Usage is billed at the rates of the period it was used in. Annual plans only, and only where the organisation's country has a CPI figure or a manual rate. Defaults to false. Cannot be changed through the API after creation.

charges
object[]
Maximum array length: 50

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.

invoice
object | null
required

The first invoice. Null in setup mode, where none is raised, and for a plan with no recurring fee sold with no add-ons or charges, which has nothing to bill for its first period. Check xero.sync_status.