curl --request POST \
  --url https://api.saasybill.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer_code": "ACME-001",
  "charges": [
    {
      "charge": "5d0c7e2a-91b4-4f3e-8a6d-2c1b9e7f4a10"
    }
  ],
  "reference": "PO-4471"
}
'

{
  "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e44",
  "object": "invoice",
  "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
  "subscription": null,
  "number": "INV-0057",
  "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": "450.0000",
  "total": "495.0000",
  "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": "3d4e5f6a-7b8c-4d9e-a0f1-2b3c4d5e6f99",
      "type": "charge",
      "revenue_type": "one_time",
      "meter": null,
      "usage_quantity": null,
      "name": "Onboarding",
      "description": "One-time charge",
      "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 `invoices:write` scope.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "not_found",
    "code": "charge_not_found",
    "message": "There is no charge with that id.",
    "param": "charges.0.charge",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "conflict",
    "code": "one_time_account_not_set",
    "message": "Choose the Xero account that one-time charges are recorded in first.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "`charges.0.price`: This charge's price cannot be overridden. Leave `price` out to bill its own.",
    "param": "charges.0.price",
    "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"
  }
}

Invoices

Create an invoice for one-time charges

Bills a customer once for one or more charges, with no subscription, under the same rules as the New Invoice form. It is never a subscription invoice, and it is not recurring revenue. It is recorded in the organisation’s one-time charge account in Xero. Idempotency-Key is required: a repeat of this request would otherwise be a second invoice and a second bill. A retry with the same key and body returns the first response. If Xero refuses the invoice it still exists here and the response is 201 with xero.sync_status of failed. Whether Xero emails it follows the organisation’s default invoice status and minimum invoice amount. 409 one_time_account_not_set until an owner or admin chooses that account.

POST

invoices

curl --request POST \
  --url https://api.saasybill.com/v1/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "customer_code": "ACME-001",
  "charges": [
    {
      "charge": "5d0c7e2a-91b4-4f3e-8a6d-2c1b9e7f4a10"
    }
  ],
  "reference": "PO-4471"
}
'

{
  "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e44",
  "object": "invoice",
  "customer": "3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11",
  "subscription": null,
  "number": "INV-0057",
  "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": "450.0000",
  "total": "495.0000",
  "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": "3d4e5f6a-7b8c-4d9e-a0f1-2b3c4d5e6f99",
      "type": "charge",
      "revenue_type": "one_time",
      "meter": null,
      "usage_quantity": null,
      "name": "Onboarding",
      "description": "One-time charge",
      "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 `invoices:write` scope.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "not_found",
    "code": "charge_not_found",
    "message": "There is no charge with that id.",
    "param": "charges.0.charge",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "conflict",
    "code": "one_time_account_not_set",
    "message": "Choose the Xero account that one-time charges are recorded in first.",
    "request_id": "req_4f1a9c2e7b8d3a605e1c9f02"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "`charges.0.price`: This charge's price cannot be overridden. Leave `price` out to bill its own.",
    "param": "charges.0.price",
    "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 invoices:write scope and an Idempotency-Key. See Authentication and Bill a customer once.

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.) invoices:write (Bill a customer once for charges, without a subscription.) credit_notes:read (List and look up credit notes, and where their credit was applied.) usage:write (Send usage events, which are billed to the subscription they name.)

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:

"bill_2026-10_acme"

Body

application/json

charges

object[]

required

What to bill, once. All in one currency, each charge at most once.

Required array length: 1 - 50 elements

Show child attributes

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.

reference

string | null

Maximum string length: 255

Response

The invoice was created. If Xero refused it, xero.sync_status is failed and the invoice still exists.

string

required

object

string

required

Allowed value: "invoice"

customer

string

required

subscription

string | null

required

number

string | null

required

Xero's invoice number, once it is in Xero.

reference

string | null

required

status

enum<string>

required

Available options:

draft,

awaiting_approval,

approved,

paid,

voided,

deleted,

not_in_external

currency

string

required

invoice_date

string<date-time>

required

ISO 8601, UTC.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

due_date

string<date-time> | null

required

ISO 8601, UTC.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

subtotal

string

required

Excluding tax.

total

string

required

Including tax, as Xero returns it.

credit_note_amount

string

required

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

amount_paid

string | null

required

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

sent

boolean

required

xero

object

required

Show child attributes

created

string<date-time>

required

ISO 8601, UTC.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

lines

object[]

Show child attributes

Getting started

Fundamentals

Integration guides

Webhooks

Organisation

Customers

Plans

Charges

Subscriptions

Invoices

Credit notes

Usage

Create an invoice for one-time charges

Authorizations

Headers

Body

Response