> ## 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.
# List credit notes
> Read-only, with the same filters as invoices. Each shows where its credit has been applied.
Requires the `credit_notes:read` scope. See [Authentication](/api-reference/authentication#scopes).
## OpenAPI
````yaml /api-reference/openapi.json get /v1/credit_notes
openapi: 3.1.0
info:
title: Saasybill API
version: 1.0.0
description: >-
Create and manage subscriptions in Saasybill from your own platform.
**Authentication.** `Authorization: Bearer saasybill_live_…`. Create keys
under Developer Settings.
**Idempotency.** Send an `Idempotency-Key` on writes. It is required to
create a subscription.
**Webhooks.** Saasybill calls your URL when something changes. Events:
`customer.created`, `customer.updated`, `customer.deleted`,
`subscription.created`, `subscription.updated`, `subscription.ended`,
`subscription.restored`, `subscription.deleted`, `invoice.created`,
`invoice.updated`, `invoice.paid`, `invoice.voided`, `invoice.deleted`,
`credit_note.created`, `credit_note.updated`, `credit_note.voided`,
`credit_note.deleted`. Each request is signed: `Saasybill-Signature: t=,v1=`, where `v1` is `HMAC-SHA256(secret, ".")`.
Reject a `t` more than five minutes old. Deliveries are at-least-once,
retried for about 20 hours, and unordered: de-duplicate on the event `id`.
Changes are detected about once a minute, so an event can arrive up to a
minute late, and changes inside one minute are combined.
**Testing.** Create a sandbox under Developer Settings → API Keys, connect
it to a Xero Demo Company, and use a test key (`saasybill_test_…`) created
inside it. A test key works only in its sandbox, which sends no emails and
is never billed. Your plans, customers and subscriptions can be copied into
the sandbox when it is created or reset, and its test clock can be advanced
to see renewals without waiting. `GET /v1/organisation` returns `livemode:
false` for a sandbox.
servers:
- url: https://app.saasybill.com/api
description: Production
security: []
tags:
- name: Organisation
description: The organisation an API key belongs to.
- name: Customers
description: >-
Customers are synced from Xero. Create one only where the organisation
allows it.
- name: Plans
description: Read the pricing plans you can sell.
- name: Charges
description: Read the one-off fees that can be added to a new subscription.
- name: Subscriptions
description: Create subscriptions, change units, and end or restore them.
- name: Invoices
description: Read the invoices Saasybill raises in Xero.
- name: Credit notes
description: >-
Read the credit notes Saasybill raises in Xero, and where their credit was
applied.
paths:
/v1/credit_notes:
get:
tags:
- Credit notes
summary: List credit notes
description: >-
Read-only, with the same filters as invoices. Each shows where its
credit has been applied.
operationId: get_v1_credit_notes
parameters:
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 25
- name: starting_after
in: query
description: The id of the last object on the previous page.
schema:
type: string
- name: subscription
in: query
description: A subscription id.
schema:
type: string
- name: customer
in: query
description: A customer id.
schema:
type: string
- name: status
in: query
description: Only these statuses, comma-separated. Every status when left out.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- draft
- awaiting_approval
- approved
- paid
- voided
- deleted
- scheduled
- not_in_external
responses:
'200':
description: Success.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
object:
type: string
const: credit_note
customer:
type: string
subscription:
type:
- string
- 'null'
number:
description: Xero's credit note number, once it is in Xero.
type:
- string
- 'null'
reference:
type:
- string
- 'null'
status:
type: string
enum:
- draft
- awaiting_approval
- approved
- paid
- voided
- deleted
- scheduled
- not_in_external
currency:
type: string
credit_note_date:
anyOf:
- type: string
format: date-time
description: ISO 8601, UTC.
- type: 'null'
subtotal:
type: string
description: Excluding tax.
total:
type: string
description: Including tax, as Xero returns it.
remaining_credit:
type: string
description: What is left to apply to invoices.
allocation_status:
anyOf:
- type: string
enum:
- applied
- partial
- unapplied
- error
- type: 'null'
sent:
type: boolean
xero:
type: object
properties:
sync_status:
type: string
enum:
- synced
- failed
- pending
credit_note_id:
type:
- string
- 'null'
sync_error:
type:
- string
- 'null'
required:
- sync_status
- credit_note_id
- sync_error
additionalProperties: false
lines:
type: array
items:
type: object
properties:
id:
type: string
name:
type:
- string
- 'null'
description:
type:
- string
- 'null'
amount:
type: string
description: Credited, excluding tax.
effective_date:
anyOf:
- type: string
format: date-time
description: ISO 8601, UTC.
- type: 'null'
required:
- id
- name
- description
- amount
- effective_date
additionalProperties: false
allocations:
description: >-
Where this credit has been applied. A reverted one
no longer counts.
type: array
items:
type: object
properties:
id:
type: string
invoice:
type: string
description: The invoice the credit was applied to.
amount:
type: string
description: A decimal string, e.g. "19.9900".
date:
type: string
format: date-time
description: ISO 8601, UTC.
status:
type: string
enum:
- active
- reverted
xero_sync_status:
type: string
enum:
- synced
- failed
- pending
required:
- id
- invoice
- amount
- date
- status
- xero_sync_status
additionalProperties: false
created:
type: string
format: date-time
description: ISO 8601, UTC.
required:
- id
- object
- customer
- subscription
- number
- reference
- status
- currency
- credit_note_date
- subtotal
- total
- remaining_credit
- allocation_status
- sent
- xero
- created
additionalProperties: false
has_more:
type: boolean
required:
- data
- has_more
additionalProperties: false
example:
data:
- id: c2d7e1a4-8b36-4d19-a5f0-7e3b9c1d2f66
object: credit_note
customer: 3b9f1c1e-6a52-4c0e-9d7e-1f6f2f0b7a11
subscription: 9d4e2b7a-13c5-4f8e-b6a0-2e1d7c9f5b33
number: CN-0007
reference: null
status: approved
currency: AUD
credit_note_date: '2026-09-29T14:00:00.000Z'
subtotal: '60.0000'
total: '66.0000'
remaining_credit: '0.0000'
allocation_status: applied
sent: false
xero:
sync_status: synced
credit_note_id: a1b2c3d4-e5f6-4789-8abc-def012345678
sync_error: null
lines:
- id: 2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e99
name: Team
description: Team � reduction from 12 to 10 seats
amount: '60.0000'
effective_date: '2026-09-29T14:00:00.000Z'
allocations:
- id: 3d4e5f6a-7b8c-4d9e-8f10-2b3c4d5e6faa
invoice: 5f8a3c9d-7e21-4b04-9c6d-0a2b4e8f1d55
amount: '66.0000'
date: '2026-10-29T14:00:00.000Z'
status: active
xero_sync_status: synced
created: '2026-09-29T14:00:05.000Z'
has_more: false
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
RateLimit-Limit:
$ref: '#/components/headers/RateLimit-Limit'
RateLimit-Remaining:
$ref: '#/components/headers/RateLimit-Remaining'
RateLimit-Reset:
$ref: '#/components/headers/RateLimit-Reset'
'401':
description: The key is missing, malformed, revoked or expired.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: authentication_error
code: invalid_api_key
message: 'Provide a valid API key as `Authorization: Bearer `.'
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'403':
description: >-
The key lacks the scope, is a test key, or the organisation has not
allowed this.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: permission_error
code: insufficient_scope
message: This API key does not have the `subscriptions:write` scope.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'404':
description: No such object.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: not_found
code: credit_note_not_found
message: There is no credit note with that id.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'409':
description: >-
The request conflicts with the current state, or with an earlier
request using the same `Idempotency-Key`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: conflict
code: idempotency_conflict
message: >-
This `Idempotency-Key` was used with a different request.
Use a new key for a different request.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'422':
description: A field is missing or invalid. `error.param` names it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: invalid_request_error
code: invalid_parameter
message: '`units`: Invalid input: expected number, received string'
param: units
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'429':
description: 'Rate limited: 120 requests a minute per key. See `Retry-After`.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: rate_limit_error
code: rate_limited
message: Too many requests. Try again in 12 seconds.
request_id: req_4f1a9c2e7b8d3a605e1c9f02
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
'500':
description: >-
Something went wrong on our side. Retry; quote `error.request_id` if
it persists.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
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
headers:
Request-Id:
$ref: '#/components/headers/Request-Id'
security:
- bearerAuth:
- credit_notes:read
components:
headers:
Request-Id:
description: A unique id for the request. Quote it when you contact support.
schema:
type: string
example: req_4f1a9c2e7b8d3a605e1c9f02
RateLimit-Limit:
description: Requests allowed per minute for this key.
schema:
type: integer
example: 120
RateLimit-Remaining:
description: Requests left in the current window.
schema:
type: integer
example: 117
RateLimit-Reset:
description: Seconds until the oldest counted request stops counting.
schema:
type: integer
example: 41
schemas:
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
enum:
- authentication_error
- permission_error
- invalid_request_error
- not_found
- conflict
- rate_limit_error
- api_error
code:
type: string
description: Stable. Branch on this, never on `message`.
message:
type: string
param:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
additionalProperties: false
required:
- error
additionalProperties: false
description: >-
Every failed request answers with this shape. Branch on `error.code`,
never on `error.message`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
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.)
`credit_notes:read` (List and look up credit notes, and where their
credit was applied.)
````