> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saasybill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Create and manage Saasybill subscriptions from your own platform

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.

<Info>
  This is the developer reference. To do the same work by hand, see the [Guides](/index) tab. To understand how plans, subscriptions and invoices fit together, start with [How Saasybill works](/core/how-saasybill-works).
</Info>

***

## Base URL

Every request goes to the same host as the app, under `/api/v1`.

```text theme={null}
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.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://app.saasybill.com/api/v1/organisation \
    -H "Authorization: Bearer $SAASYBILL_API_KEY"
  ```

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

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

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

```json Response theme={null}
{
  "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
}
```

<Tip>
  Don't have a key yet? [Create one in Developer Settings](/api-reference/authentication#create-an-api-key).
</Tip>

***

## What you can do

| Resource | Read | Write |
| - | - | - |
| [Organisation](/api-reference/organisation/retrieve-the-organisation) | Name, timezone, currency, setup mode | None |
| [Customers](/api-reference/customers/list-customers) | List, retrieve | Create, where the organisation allows it |
| [Plans](/api-reference/plans/list-plans) | List, retrieve | None |
| [Charges](/api-reference/charges/list-charges) | List, retrieve | None |
| [Subscriptions](/api-reference/subscriptions/list-subscriptions) | List, retrieve | Create, change units, end, restore |
| [Invoices](/api-reference/invoices/list-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.

<Note>
  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.
</Note>

***

## How an integration fits together

<Steps>
  <Step title="Read your catalogue">
    List plans and charges once and cache the ids and codes. Plans change rarely.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Listen for changes">
    Subscribe to [webhooks](/api-reference/webhooks/overview) to hear when invoices are raised or paid, instead of polling.
  </Step>
</Steps>

***

## Explore

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api-reference/quickstart">
    Create a key and your first subscription in minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    API keys, scopes and how to keep them safe.
  </Card>

  <Card title="Webhooks" icon="bell" href="/api-reference/webhooks/overview">
    Get told when customers, subscriptions and invoices change.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/api-reference/errors">
    Every error code and how to handle it.
  </Card>
</CardGroup>

***

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

```text theme={null}
https://app.saasybill.com/api/v1/openapi.json
```

<Info>
  The document is public. It describes the interface, not anyone's data, so you can read it before you have a key.
</Info>