List sales invoices

GEThttps://<your-url>/api/v2/sales-invoices

MCP id sales-invoices.indexAlso on this path: POST Create a sales invoice

Returns the organisation's sales invoices, newest invoice date first.

Token scope: api:read:sales_invoices
Without it: 403 insufficient-token-scope.
Permission: sales_invoices::read
Without it: 403 insufficient-permission.
Feature: Needs the billing feature on your organisation.
Without it: 404 endpoint-not-found.
Rate cost: 1 unit, read bucket. view=detail makes it 3. Adds: each include +1, q +2.
Also: If-None-Match answers 304 when nothing changed. Never cached: private, no-store. Unknown query parameters are refused, never ignored.

Both are checked, scope first. A token never does more than its user. How access is checked

Request

Example: Unsynced invoices for one customer this quarter

curl -G \
  'https://<your-url>/api/v2/sales-invoices' \
  --data-urlencode 'filter[customer_id]=1' \
  --data-urlencode 'filter[invoice_date][gte]=2026-01-01' \
  --data-urlencode 'filter[sync_status]=pending' \
  --data-urlencode 'sort=-invoice_date' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/sales-invoices?filter[customer_id]=1&filter[invoice_date][gte]=2026-01-01&filter[sync_status]=pending&sort=-invoice_date', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/sales-invoices?filter[customer_id]=1&filter[invoice_date][gte]=2026-01-01&filter[sync_status]=pending&sort=-invoice_date');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/sales-invoices?filter[customer_id]=1&filter[invoice_date][gte]=2026-01-01&filter[sync_status]=pending&sort=-invoice_date',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "customer_id": 1,
      "customer": {
        "id": 1
      },
      "project_id": 1,
      "customer_subscription_id": 1,
      "invoice_number": "…",
      "reference": "PO-4471",
      "description": "Development work, January 2026",
      "invoice_date": "2026-02-01",
      "due_date": "2026-03-03",
      "status": "draft",
      "should_email": false
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1,
      "current_page": 1,
      "last_page": 1
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

16 more fields, listed under Response

Defaults to the summary view; view=detail adds sync_error and internal_notes and costs three read units instead of one. Search with q= over the invoice number, and pass trashed=with|only to see deleted invoices. Combine filter[invoice_date][gte] and [lte] for a period, filter[status]=draft or pending_approval for the concept and approval queues in plnnrly, and filter[sync_status]=failed for invoices the accounting sync rejected. Sorting by total or invoice number is deliberately not offered, so a money-ordered page has to be sorted client-side.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

52 parameters in 7 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

pageinteger1 to 1000

Opt in to page-number paging: 1-based, at most 1000. Omit it, the default, to page by opaque cursor, which is what links.next hands you. Cannot be combined with cursor. Published only on collections that count their rows on every request.

Filters

=: equals
[in]: any of a comma-separated list
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than
[ne]: not equal

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[customer_id]integer=[in]

Customer the invoice is billed to.

A comma-separated list of at most 100 values.

filter[customer_subscription_id]integer=[in][null]

Customer subscription the invoice was generated from. Pass [null] for invoices that were not generated from a renewal.

A comma-separated list of at most 100 values.

filter[due_date]date (YYYY-MM-DD)=[gte][lte][null]

Date payment is due. Pass [null] for invoices with no term applied.

Whether the field is null.

filter[invoice_date]date (YYYY-MM-DD)=[gte][lte]

Invoice date, a zone-free calendar date. Combine [gte] and [lte] for a period.

filter[is_legacy]boolean

Whether the invoice was converted from a legacy invoice, and is therefore read-only.

filter[legacy_invoice_id]integer=[in][null]

The id of the legacy invoice this invoice was converted from, so it can be matched with GET /api/v2/invoices.

A comma-separated list of at most 100 values.

filter[paid_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lte][null]

When the invoice was settled. Pass [null] for unsettled invoices.

Whether the field is null.

filter[project_id]integer=[in][null]

Project the invoice was raised for. Pass [null] for invoices raised against no project.

A comma-separated list of at most 100 values.

filter[should_email]boolean

Whether the invoice is emailed to the customer when it syncs.

Search

qstring

Free-text search over invoice_number. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: invoice_date

Key	Sorts by
`invoice_date`	Invoice date, newest first by default.
`due_date`	Date payment is due.
`synced_at`	When the invoice last synced successfully.
`sync_attempted_at`	When the invoice was last handed to the sync.
`paid_at`	When the invoice was settled.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Includes

includestring

Comma-separated names to inline, at most five.

Path	Adds	Cost
`customer`	The customer this invoice is billed to, with their name and code. Requires the `customers::read` permission and a token scope covering the customers prefix.	+1

Other

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

Request headers

X-Request-Idstringpattern

A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a page of SalesInvoiceList rows.

dataarray of SalesInvoiceList

The rows, each a SalesInvoiceList.

meta.pagePage

per_page, next_cursor, prev_cursor, total, current_page, last_page.

linksPageLinks

self, next, prev.

Each row is a SalesInvoiceList: 28 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
RateLimit: The IETF httpapi-ratelimit-headers form of your remaining allowance on the tightest bucket this request touched.
RateLimit-Policy: The ceiling and window of that bucket, as <limit>;w=<seconds>.
X-Request-Id: The server-generated ULID correlating this response with our logs.

Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning

idinteger

Unique identifier.

customer_idinteger

Customer this invoice is billed to.

customerRef or CustomerSummary

The customer this invoice is billed to. Expanding it with ?include=customer additionally requires the customers::read permission and a token scope covering the customers prefix.

project_idinteger or null

Project this invoice was raised for, when it was raised from one.

customer_subscription_idinteger or null

Customer subscription this invoice was generated from, when it was generated from a renewal.

invoice_numberstring≤ 255Server-assigned

Invoice number, allocated by the server from the organisation's yearly sequence: B-26-00001 for an invoice raised in this flow, L-1234 for one converted from a legacy invoice. It also works in the path: GET sales-invoices/B-26-00001 works. This is the field ?q= searches.

referencestring or null≤ 255

The customer's own reference, typically a purchase-order number, reproduced on the invoice.

descriptionstring or null≤ 255

One-line description of what was invoiced.

invoice_datedate (YYYY-MM-DD)

Invoice date, a zone-free calendar date. Newest first is the default sort.

due_datedate (YYYY-MM-DD) or null

Date payment is due, a zone-free calendar date. Null when no term was applied.

statusstringServer-assigned

Lifecycle status. Resolved by the server on create and never writable: a caller without sales_invoices::finalize creates a pending_approval invoice, and any update by such a caller returns the invoice to pending_approval.

draftpending_approvalsentpaidoverduecancelled

New values may be added.

should_emailboolean

Whether the invoice is emailed to the customer when it syncs. The email is sent through the accounting integration, so it is forced to false in an organisation with no integration configured. Writing it requires sales_invoices::finalize.

subtotaldecimal (2 dp)Server-assigned

Sum of the row line totals excluding VAT, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

vat_totaldecimal (2 dp)Server-assigned

Sum of the row VAT amounts, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

totaldecimal (2 dp)Server-assigned

Subtotal plus VAT, as a decimal string. Recomputed from the rows; never written directly.

2 decimal places, may be negative

exact_invoice_idstring or null≤ 255Server-assigned

The accounting system's own identifier for this invoice, written by the sync. Not a local id.

exact_journalstring or null≤ 255Server-assigned

Sales journal the invoice is booked in, resolved from the organisation's accounting settings on create. Null in an organisation with no integration configured.

sync_statusstringServer-assigned

How far the invoice has got through the accounting sync. Set on create: local in an organisation with no integration configured, pending otherwise.

pendingsyncedfailedlocal

New values may be added.

sync_errorstring or nullDetail onlyServer-assignedMultiline

Why the last sync attempt failed, verbatim from the accounting system. Null while nothing has failed.

synced_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice last synced successfully.

sync_attempted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice was last handed to the sync, successfully or not.

paid_attimestamp (YYYY-MM-DDThh:mm:ssZ) or nullServer-assigned

When the invoice was settled. Set on create for a local invoice that is immediately definitive; otherwise written when payment is registered.

is_legacybooleanServer-assigned

Whether this invoice was converted from a legacy invoice. Such an invoice is read-only: PATCH and DELETE answer 409 state-conflict with reason locked_by_legacy.

legacy_invoice_idinteger or nullServer-assigned

The id of the legacy invoice this invoice was converted from, so it can be matched with GET /api/v2/invoices. The legacy invoice may since have been removed.