Introduction

The Saasybill API lets your software do what your team does in the app. A signup on your platform creates a subscription. A seat change on your platform updates its units. Saasybill raises the invoice in Xero each time.

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 same host as the app, under /api/v1.

https://app.saasybill.com/api/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://app.saasybill.com/api/v1/organisation \
  -H "Authorization: Bearer $SAASYBILL_API_KEY"

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

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

import os
import requests

response = requests.get(
    "https://app.saasybill.com/api/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
}

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

Plans, charges and customers are managed in the app and synced from Xero. The API reads them so your platform can sell against them. Subscriptions are the object your platform writes.

Not available yet: add-ons, catalogue writes (plans, charges, categories), credit notes, invoice writes, managing keys or webhook endpoints through the API, a sandbox, 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 or usage change on your platform, send the new total with POST /v1/subscriptions/{id}/units. Saasybill decides whether to invoice now, defer to renewal, or credit.

Listen for changes

Subscribe to webhooks to hear when invoices are raised or paid, instead of polling.

Explore

Quickstart

Create a key and your first subscription in minutes.

Authentication

API keys, scopes and how to keep them safe.

Webhooks

Get told when customers, subscriptions and invoices change.

Errors

Every error code and how to handle it.

OpenAPI document

The full API is described as an OpenAPI 3.1 document. Import it into Postman or Insomnia, or use it to generate a client in your language.

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

The document is public. It describes the interface, not anyone’s data, so you can read it before you have a key.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Base URL

Your first request

What you can do

How an integration fits together

Explore

Quickstart

Authentication

Webhooks

Errors

OpenAPI document

​Base URL

​Your first request

​What you can do

​How an integration fits together

​Explore

Quickstart

Authentication

Webhooks

Errors

​OpenAPI document

Base URL

Your first request

What you can do

How an integration fits together

Explore

OpenAPI document