Create a subscription

Creates the subscription and its first invoice, and sends the invoice to Xero, under the same rules as the New Subscription form. Idempotency-Key is required: a repeat of this request would otherwise be a second subscription and a second bill. A retry with the same key and body returns the first response. If Xero refuses the invoice the subscription still exists and the response is 201 with invoice.xero.sync_status of failed.

POST /v1/subscriptions

cURL

Per unit plan, by code

curl --request POST \
  --url https://api.saasybill.com/v1/subscriptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer_code": "ACME-001",
  "plan_code": "TEAM-MONTHLY",
  "units": 10,
  "start_date": "2026-09-30",
  "discount_percent": "10",
  "label": "Acme � Team plan",
  "invoice_reference": "PO-4471"
}
'

201

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
  "customer_code": "ACME-001",
  "plan": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
  "status": "active",
  "currency": "AUD",
  "interval": {
    "unit": "month",
    "count": 1
  },
  "timezone": "Australia/Sydney",
  "start_date": "2026-09-30",
  "renewal_date": "2026-10-30",
  "end_date": null,
  "units": 10,
  "minimum_units": 5,
  "discount_percent": "10.00",
  "cancel_at_period_end": false,
  "end_after_cycles": null,
  "label": "Acme � Team plan",
  "invoice_reference": "PO-4471",
  "renewal_value": "108.0000",
  "usage_value": "0.0000",
  "usage_value_annual": "0.0000",
  "minimum_usage_value": "0.0000",
  "meters": [],
  "cpi_enabled": false,
  "created": "2026-09-30T04:12:00.000Z",
  "invoice": {
    "id": "5f8a3c9d-7e21-4b04-9c6d-0a2b4e8f1d55",
    "object": "invoice",
    "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
    "subscription": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
    "number": "INV-0042",
    "reference": "PO-4471",
    "status": "awaiting_approval",
    "currency": "AUD",
    "invoice_date": "2026-09-29T14:00:00.000Z",
    "due_date": "2026-10-29T13:00:00.000Z",
    "subtotal": "558.0000",
    "total": "613.8000",
    "credit_note_amount": "0.0000",
    "amount_paid": null,
    "sent": false,
    "xero": {
      "sync_status": "synced",
      "invoice_id": "f0e9d8c7-b6a5-4f43-9210-fedcba987654",
      "sync_error": null
    },
    "lines": [
      {
        "id": "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c77",
        "type": "subscription",
        "revenue_type": "new_subscription",
        "meter": null,
        "usage_quantity": null,
        "name": "Team",
        "description": "Team � 10 seats",
        "units": 10,
        "amount": "120.0000",
        "discount_amount": "12.0000",
        "charge_amount": "108.0000",
        "effective_date": "2026-09-29T14:00:00.000Z"
      },
      {
        "id": "1b2c3d4e-5f6a-4b7c-9d8e-0f1a2b3c4d88",
        "type": "charge",
        "revenue_type": "new_subscription",
        "meter": null,
        "usage_quantity": null,
        "name": "Onboarding",
        "description": "One-off setup and training",
        "units": null,
        "amount": "450.0000",
        "discount_amount": "0.0000",
        "charge_amount": "450.0000",
        "effective_date": "2026-09-29T14:00:00.000Z"
      }
    ],
    "created": "2026-09-30T04:12:01.000Z"
  }
}

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.) credit_notes:read (List and look up credit notes, and where their credit was applied.)

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.

Show child attributes

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 · string number

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

discount_percent · string number

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 · string number

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

Show child attributes

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

Show child attributes

Response

201

application/json

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

Show child attributes

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

minimum_units · integer · required

discount_percent · string · required

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

cancel_at_period_end · boolean · required

end_after_cycles · integer | null · required

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.

Show child attributes

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.

Show child attributes