Quickstart

This walkthrough takes you from no key to a subscription with an invoice in Xero. Each step is one request.

You need a Saasybill organisation connected to Xero, with at least one plan and one customer. If you are testing, read Testing first and use a Xero Demo Company.

Before you start

Create an API key

Only an owner or admin can create keys.

Open Organisation Settings and go to Developer Settings, then API Keys.
Click Create API Key.
Enter a Name, such as Signup integration.
Choose the Permissions the key needs. For this walkthrough, select all of them.
Choose when the key Expires, or choose Never.
Click Create Key.

Copy the key from the Your New API Key dialog. It is shown once and cannot be retrieved later.

Store it as an environment variable

Keep the key out of your code and your repository.

export SAASYBILL_API_KEY="saasybill_live_…"

Make your first subscription

Check the connection

Retrieve the organisation. A 200 response confirms the key works.

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

Note setup_mode. While it is true, Saasybill creates subscriptions but does not raise invoices in Xero.

Find the plan

Look up the plan by the code you gave it in the app.

curl "https://app.saasybill.com/api/v1/plans?code=TEAM-MONTHLY" \
  -H "Authorization: Bearer $SAASYBILL_API_KEY"

Response

{
  "data": [
    {
      "id": "b6c1e0a4-2f7d-4a61-8f0c-5d3e9a7b2c44",
      "object": "plan",
      "code": "TEAM-MONTHLY",
      "name": "Team",
      "type": "per_unit",
      "interval": { "unit": "month", "count": 1 },
      "currency": "AUD",
      "price": "12.0000",
      "minimum_units": 5,
      "free_units": 0,
      "unit_labels": { "singular": "seat", "plural": "seats" },
      "allows_price_override": false,
      "status": "active",
      "tiers": [],
      "created": "2026-06-02T23:10:44.000Z"
    }
  ],
  "has_more": false
}

Find the customer

Customers come from Xero. Look one up by the code you use for them.

curl "https://app.saasybill.com/api/v1/customers?code=ACME-001" \
  -H "Authorization: Bearer $SAASYBILL_API_KEY"

If the customer doesn’t exist yet, see Customers and Xero.

Create the subscription

Send the customer, the plan and the units. The Idempotency-Key is required. Use an id from your own system, such as the signup id, so a retry can never bill twice.

curl https://app.saasybill.com/api/v1/subscriptions \
  -H "Authorization: Bearer $SAASYBILL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup_8f3a2c1d" \
  -d '{
    "customer_code": "ACME-001",
    "plan_code": "TEAM-MONTHLY",
    "units": 10,
    "discount_percent": "10",
    "invoice_reference": "PO-4471"
  }'

Response (trimmed)

{
  "id": "9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33",
  "object": "subscription",
  "status": "active",
  "units": 10,
  "renewal_date": "2026-10-30",
  "renewal_value": "108.0000",
  "invoice": {
    "id": "5f8a3c9d-7e21-4b04-9c6d-0a2b4e8f1d55",
    "object": "invoice",
    "number": "INV-0042",
    "status": "awaiting_approval",
    "xero": { "sync_status": "synced", "invoice_id": "f0e9d8c7-b6a5-4f43-9210-fedcba987654", "sync_error": null }
  }
}

Check the invoice reached Xero

Read invoice.xero.sync_status. synced means the invoice is in Xero. failed means Xero refused it, but the subscription still exists. See Create a subscription.

Change the units

When the customer adds seats, send the new total, not the difference.

curl https://app.saasybill.com/api/v1/subscriptions/9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33/units \
  -H "Authorization: Bearer $SAASYBILL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "units": 15,
    "prorate": true,
    "proration_behaviour": "charge_immediately",
    "effective_date": "2026-10-08"
  }'

The response’s change object says what Saasybill did. See Change units.

Next steps

Create a subscription

Every option, with request bodies for common cases.

Set up webhooks

Hear about paid invoices without polling.

Handle errors

Branch on error codes, not messages.

Retry safely

How idempotency keys protect against double billing.

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Before you start

Make your first subscription

Next steps

Create a subscription

Set up webhooks

Handle errors

Retry safely

​Before you start

​Make your first subscription

​Next steps

Create a subscription

Set up webhooks

Handle errors

Retry safely

Before you start

Make your first subscription

Next steps