Introduction

Use the Saasybill API to create subscriptions, change units and report usage from your own platform. Each billable change raises an invoice in Xero.

This is the developer reference. To do the same work by hand, see the Guides tab. To understand how plans, subscriptions and invoices fit together, start with How Saasybill works.

Base URL

Every request goes to the API host, api.saasybill.com, under /v1.

https://api.saasybill.com/v1

Requests and responses are JSON. Send Content-Type: application/json on every request with a body.

Your first request

Send your API key as a bearer token. This request returns the organisation the key belongs to, so it doubles as a connectivity check.

curl https://api.saasybill.com/v1/organisation \
  -H "Authorization: Bearer $SAASYBILL_API_KEY"

const response = await fetch("https://api.saasybill.com/v1/organisation", {
  headers: { Authorization: `Bearer ${process.env.SAASYBILL_API_KEY}` },
});

console.log(await response.json());

import os
import requests

response = requests.get(
    "https://api.saasybill.com/v1/organisation",
    headers={"Authorization": f"Bearer {os.environ['SAASYBILL_API_KEY']}"},
)

print(response.json())

Response

{
  "id": "7c3e9a1b-5d20-4f68-a4b7-8e6d2c0f9a99",
  "object": "organisation",
  "name": "Northwind Software",
  "timezone": "Australia/Sydney",
  "default_currency": "AUD",
  "setup_mode": false,
  "can_create_xero_contacts": true,
  "livemode": true
}

Don’t have a key yet? Create one in Developer Settings.

What you can do

Resource	Read	Write
Organisation	Name, timezone, currency, setup mode	None
Customers	List, retrieve	Create, where the organisation allows it
Plans	List, retrieve	None
Charges	List, retrieve	None
Subscriptions	List, retrieve	Create, change units, end, restore
Invoices	List, retrieve	None
Credit notes	List, retrieve	None
Usage	None	Report usage events

Plans and charges are managed in the app, and customers sync from Xero. Your platform reads them and writes subscriptions.

Not available yet: add-ons, catalogue writes (plans, charges, categories, meters), reading reported usage back, invoice and credit note writes, managing keys or webhook endpoints through the API, OAuth, and SDKs.

How an integration fits together

Read your catalogue

List plans and charges once and cache the ids and codes. Plans change rarely.

Create subscriptions on signup

Send POST /v1/subscriptions with an Idempotency-Key. Saasybill creates the subscription and its first invoice, and sends the invoice to Xero.

Keep units in sync

When seats change on your platform, send the new total with POST /v1/subscriptions/{id}/units. Saasybill invoices now, defers the charge to renewal, or issues a credit note, depending on the prorate option and the plan type.

Report usage

For plans that bill by usage, send what each customer used with POST /v1/usage_events. Saasybill totals it and bills it in arrears when the period ends. See Usage-based billing.

Listen for changes

Subscribe to webhooks for invoice and subscription events instead of polling.

Explore

Quickstart

Create a key, create a subscription and change its units.

Authentication

API keys and scopes.

Webhooks

Events for customers, subscriptions, invoices and credit notes.

Errors

Error format, codes and handling.

OpenAPI document

The full API is described as an OpenAPI 3.1 document. Import it into Postman or Insomnia, or generate a client from it.

https://api.saasybill.com/v1/openapi.json

The document is public and needs no key.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Credit notes

Usage

Base URL

Your first request

What you can do

How an integration fits together

Explore

Quickstart

Authentication

Webhooks

Errors

OpenAPI document