List invoices for an Organization

get

https://api.benjipays.com/v2/invoices

Returns paginated Benji-controlled camelCase invoice summaries for the authenticated organization. Field names match filter/query params (invoiceNumber, dueDate, customerId → customer.id). List responses never include the stored invoice object — use GET /invoices/:invoiceId?include=accounting for that.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

status

string

enum

open returns every unpaid invoice regardless of due date (so it also includes invoices that are past due — their status field in the response may read overdue). overdue narrows that same set to unpaid invoices whose due date has passed. paid returns invoices with a zero balance.

Allowed:

customerId

string

length ≤ 100

Filter to invoices for a single customer. Use the accounting system customer ID (QuickBooks Id, Xero ContactID, Business Central id, QBD ListID).

invoiceDateStart

string

^\d{4}-\d{2}-\d{2}$

Start of invoice-date range (inclusive). Format: YYYY-MM-DD (e.g. 2024-07-02). Compared as a calendar date string to stored invoiceDate / TxnDate (not expanded to UTC day bounds). Optional independently of invoiceDateEnd. Same start and end day is valid.

invoiceDateEnd

string

^\d{4}-\d{2}-\d{2}$

End of invoice-date range (inclusive). Format: YYYY-MM-DD (e.g. 2024-07-31). Compared as a calendar date string to stored invoiceDate / TxnDate (not expanded to UTC day bounds). Optional independently of invoiceDateStart. Same start and end day is valid.

dueDateStart

string

^\d{4}-\d{2}-\d{2}$

Start of due-date range (inclusive). Format: YYYY-MM-DD (e.g. 2024-07-02). Compared as a calendar date string to stored dueDate / DueDate (not expanded to UTC day bounds). Optional independently of dueDateEnd. Same start and end day is valid.

dueDateEnd

string

^\d{4}-\d{2}-\d{2}$

End of due-date range (inclusive). Format: YYYY-MM-DD (e.g. 2024-07-31). Compared as a calendar date string to stored dueDate / DueDate (not expanded to UTC day bounds). Optional independently of dueDateStart. Same start and end day is valid.

totalMin

number

≥ 0

totalMax

number

≥ 0

balanceMin

number

≥ 0

balanceMax

number

≥ 0

invoiceNumber

string

length ≤ 50

Filter by invoice number (the human-readable invoice number from the accounting system, e.g. INV-1001).

currency

string

^[A-Z]{3}$

termsId

string

length ≤ 100

Filter by payment terms ID from the accounting system (e.g. QuickBooks SalesTermRef.value).

emailed

string

enum

Allowed:

sort

string

enum

Sort field (dueDate, invoiceDate, invoiceNumber, total, balance, customerName). customerName sorts by customer.name.

Allowed:

order

string

enum

Sort direction. Accepted values: asc, desc. Defaults to desc when omitted.

Allowed:

limit

integer

1 to 1000

Defaults to 20

offset

integer

0 to 9007199254740991

Defaults to 0

Headers

X-Request-ID

uuid

Optional client-supplied unique ID for one request. The server generates a UUID v4 if omitted and always echoes the value in the response.

X-Correlation-ID

uuid

Optional ID that flows across service boundaries for distributed tracing. The server generates a UUID v4 if omitted and always echoes the value in the response.

string

enum

Defaults to application/json

Generated from available response content types

Allowed:

Responses

200Paginated invoice list (summary DTO only)

400Bad request — request validation failed (invalid query/path parameters; type …/validation-error with optional errors[]), and/or organization has no accounting integration configured.

401Unauthorized — invalid or missing authentication, or API access is not active for this organization (disabled or missing).

403Forbidden — missing required OAuth scope (organizations:invoices:read), insufficient live mapping permission on the API key owner (e.g. companyAdmin), and/or free trial ended without billing enabled. Scope, mapping, and billing state are independent gates; see response detail.

404Organization not found

429Too Many Requests