Create a subscription

curl --request POST \
  --url https://app.saasybill.com/api/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"
}
'

{
  "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",
  "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",
        "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",
        "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"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Provide a valid API key as `Authorization: Bearer <key>`.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the `subscriptions:write` scope.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "not_found",
    "code": "subscription_not_found",
    "message": "There is no subscription with that id.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "conflict",
    "code": "idempotency_conflict",
    "message": "This `Idempotency-Key` was used with a different request. Use a new key for a different request.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "`units`: Invalid input: expected number, received string",
    "param": "units",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Try again in 12 seconds.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side. Retry the request; if it keeps failing, quote the request id.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

POST

subscriptions

curl --request POST \
  --url https://app.saasybill.com/api/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"
}
'

{
  "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",
  "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",
        "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",
        "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"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Provide a valid API key as `Authorization: Bearer <key>`.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_scope",
    "message": "This API key does not have the `subscriptions:write` scope.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "not_found",
    "code": "subscription_not_found",
    "message": "There is no subscription with that id.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "conflict",
    "code": "idempotency_conflict",
    "message": "This `Idempotency-Key` was used with a different request. Use a new key for a different request.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "`units`: Invalid input: expected number, received string",
    "param": "units",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limited",
    "message": "Too many requests. Try again in 12 seconds.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Something went wrong on our side. Retry the request; if it keeps failing, quote the request id.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

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

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 flat fee plan.

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

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

charges

object[]

Maximum array length: 50

Show child attributes

Response

Success.

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

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

created

string<date-time>

required

ISO 8601, UTC.

invoice

object | null

required

The first invoice. Null in setup mode, where none is raised. Check xero.sync_status.

Show child attributes

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Authorizations

Headers

Body

Response