List invoices

GET/v1/invoices

Query parameters

filter[id] string

Filter invoices by id. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1A

filter[shortId] string

Filter invoices by shortId. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1A

filter[clientId] string

Filter invoices by clientId. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1C

filter[projectId] string

Filter invoices by projectId. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1D

filter[contactId] string

Filter invoices by contactId. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1E

filter[bankAccountId] string

Filter invoices by bankAccountId. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1A

filter[invoiceRecurringId] string

Filter invoices by invoiceRecurringId. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1A

filter[name] string

Filter invoices by name. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.example

filter[description] string

Filter invoices by description. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.example

filter[notes] string

Filter invoices by notes. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.example

filter[tags] string

Filter invoices by tags. Use operator.value syntax.

in, is operators

Examplein.(example)

filter[settled] string

Filter invoices by settled. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.true

filter[pendedAt] string

Filter invoices by pendedAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[cancelledAt] string

Filter invoices by cancelledAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[createdAt] string

Filter invoices by createdAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[createdBy] string

Filter invoices by createdBy. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.example

filter[updatedAt] string

Filter invoices by updatedAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[updatedBy] string

Filter invoices by updatedBy. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.example

filter[deletedAt] string

Filter invoices by deletedAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[deletedBy] string

Filter invoices by deletedBy. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, in, is operators

Exampleeq.example

filter[currencyId] string

Filter invoices by currencyId. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.01JQ2T5Y5Q3R8W9N6M4K2H7P1F

filter[currencyCode] string

Filter invoices by currencyCode. Use operator.value syntax.

eq, neq, in, is operators

Exampleeq.SAR

filter[amount] string

Filter invoices by amount. Use operator.value syntax.

eq, neq, gt, gte, lt, lte operators

Exampleeq.100.00

filter[activityAt] string

Filter invoices by activityAt. Use operator.value syntax.

eq, neq, gt, gte, lt, lte, is operators

Exampleeq.2026-01-15T12:00:00Z

filter[status] string

Filter invoices by status. Use operator.value syntax.

eq, neq, in operators

Exampleeq.draft

select string

Comma-separated fields. Select a declared relation with relation(field,field).

declared fields and relations only

Exampleid,shortId

order string

Order by field.asc or field.desc. Repeat fields with commas.

repeat fields separated by commas

Exampleid.asc,shortId.asc

limit integer

Maximum records returned. Defaults to 25.

1 to 1000

Example25

cursor string

Opaque continuation cursor returned by the previous page.

Exampleopaque-cursor

count string

Request an exact count. This may cost more than a normal page.

exact

Exampleexact

search string

Search matching resource fields.

Exampleconsulting

Query options

Use filter, select, order, limit, cursor, count, search. The default limit is 25; the maximum is 1000.

Filterable: id, shortId, clientId, projectId, contactId, bankAccountId, invoiceRecurringId, name, description, notes, tags, settled, pendedAt, cancelledAt, createdAt, createdBy, updatedAt, updatedBy, deletedAt, deletedBy, currencyId, currencyCode, amount, activityAt, status.

Selectable: id, shortId, clientId, projectId, contactId, projectWebsite, clientWebsite, clientType, contactWebsite, bankAccountId, invoiceRecurringId, recurringSourceName, currency, name, description, notes, tags, entries, modifiers, totals, recurringOn, settledAt, settled, pendedAt, cancelledAt, createdAt, createdBy, updatedAt, updatedBy, deletedAt, deletedBy.

Sortable: id, shortId, clientId, projectId, contactId, bankAccountId, invoiceRecurringId, name, description, notes, settled, pendedAt, cancelledAt, createdAt, createdBy, updatedAt, updatedBy, deletedAt, deletedBy, currencyId, currencyCode, amount, activityAt, status.

Errors: invalid_input, query_invalid, unauthenticated, not_found, forbidden, plan_limit, conflict, rate_limited, request_quota, unavailable, internal_error.

Headers

authorization string required

Bearer workspace API key.

ExampleBearer $NQD_API_KEY

workspace-id string required

Workspace scope for the request. Required for workspace operations and must belong to the authenticated identity.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1A

An Invoice is an incoming service source. Use Client and Project for the service context and Entries for the priced units. It may be unpaid or partially paid; record cash separately through Transactions.

Response

200Success

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

data object[]

Returned records. Collections and batches use an array; single records use an object.

ShowHide 31 properties

data[].id string

Opaque identifier for this resource or reference.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1P

data[].shortId string

ID of the related short.

ExampleINV-0001

data[].clientId string

Optional client reference. Null means the current workspace owns the record; do not create a placeholder client.

Examplenull

data[].projectId string

Project identifier within the current workspace.

Examplenull

data[].contactId string

Contact identifier for the invoice, expense, income, or project contact in the current workspace.

Examplenull

data[].projectWebsite string nullable

project website for this invoice.

Examplehttps://example.com

data[].clientWebsite string[] nullable

client website for this invoice.

Example1 item

data[].clientType string nullable

client type for this invoice.

Allowed values: "individual", "company", "government"

Exampleindividual

data[].contactWebsite string[] nullable

contact website for this invoice.

Example1 item

data[].bankAccountId string

ID of the related bank account.

Examplenull

data[].invoiceRecurringId string

ID of the related invoice recurring.

Examplenull

data[].recurringSourceName string nullable

recurring source name for this invoice.

ExampleConsulting services

data[].currency object

Referenced currency with its opaque ID and ISO 4217 currency code.

ShowHide 3 properties

data[].currency.id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1F

data[].currency.code string

ISO 4217 currency code, such as SAR or USD.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data[].currency.conversion object

Currency conversion quote used for reporting, including source, target, and rate.

ShowHide 3 properties

data[].currency.conversion.from string

ISO 4217 code of the source currency in this persisted quote.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data[].currency.conversion.to string

ISO 4217 code of the target reporting currency in this persisted quote.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleSAR

data[].currency.conversion.rate string

Exact decimal conversion rate from the quote source currency to its target currency.

Maximum length: 128 characters.

Example1.00

data[].name string

Display name of the record.

ExampleConsulting services

data[].description string

Optional human-readable description of the record.

ExampleConsulting services for January 2026

data[].notes string

Notes attached to the record.

ExampleConsulting services

data[].tags string[] nullable

Tags assigned to the record.

Example1 item

data[].entries object[]

Applied economic entries. Each entry is a reusable priced unit for a product, service, plan, or other calculable line. Entry prices are authored net prices; the workspace tax modifier calculates VAT.

at most 1000 items

ShowHide 7 properties

data[].entries[].id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1H

data[].entries[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleConsulting services

data[].entries[].name string

Display name of the record.

Maximum length: 10000 characters.

ExampleConsulting service

data[].entries[].description string

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleMonthly consulting service

data[].entries[].quantity string

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example2.00

data[].entries[].unit string

Unit code from the workspace catalog.

Minimum length: 1 character. · Maximum length: 128 characters.

Examplehour

data[].entries[].pricePerUnit string

Exact decimal string used for financial calculations. Do not round or convert it to a display number.

Maximum length: 128 characters.

Example100.00

data[].modifiers object[]

Modifiers applied to one entry or the whole source. Supported values are signed fixed amounts or percentages, such as `15.00%` or `-25.00`; arbitrary multiplication and division are not supported.

at most 1000 items

ShowHide 6 properties

data[].modifiers[].id string

Opaque identifier for this resource or reference.

Minimum length: 1 character. · Maximum length: 128 characters.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1J

data[].modifiers[].appliedId string nullable

Stable identity of this saved modifier application. Preserve it when updating a financial record, including repeated uses of the same catalog modifier.

Minimum length: 1 character. · Maximum length: 128 characters.

ExampleConsulting services

data[].modifiers[].name string

Display name of the record.

Minimum length: 1 character. · Maximum length: 10000 characters.

ExampleVAT

data[].modifiers[].description string nullable

Optional human-readable description of the record.

Maximum length: 10000 characters.

ExampleValue added tax

data[].modifiers[].entryIndex number nullable

entry index within modifiers.

Example100

data[].modifiers[].value string

Modifier value. A trailing `%` marks a percentage; a leading `-` marks a decrease. Modifiers support fixed or percentage adjustments, not arbitrary multiplication or division.

Maximum length: 128 characters.

Example15.00%

data[].totals object nullable

totals for this invoice.

ShowHide 7 properties

data[].totals.lineTotals object nullable

line totals within totals.

data[].totals.base string nullable

base within totals.

Example200.00

data[].totals.net string

Total before tax and other modifiers.

Example200.00

data[].totals.tax string

Tax calculated from the workspace payable modifier.

Example30.00

data[].totals.gross string

Total after tax and other price modifiers.

Example230.00

data[].totals.payable string

Amount due after all applied modifiers.

Example230.00

data[].totals.reporting string nullable

Amount converted to the workspace reporting currency.

Example230.00

data[].recurringOn string nullable

recurring on for this invoice.

Example2026-01-15

data[].settled boolean nullable

Whether effective transactions cover the amount due.

Examplefalse

data[].createdBy string

Identifier of the identity that created the record.

Example01JQ2T5Y5Q3R8W9N6M4K2H7P1B

data[].updatedBy string

Identifier of the identity that last updated the record.

Examplenull

data[].deletedBy string

deleted by for this invoice.

Examplenull

data[].settledAt string nullable

Timestamp when effective transactions covered the amount due.

Example2026-01-15T12:00:00.000Z

data[].pendedAt string

ISO 8601 timestamp for pended.

Examplenull

data[].cancelledAt string

ISO 8601 timestamp for cancelled.

Examplenull

data[].createdAt string

ISO 8601 timestamp for the authored or payment event. Recurring records preserve their scheduled occurrence.

Example2026-01-15T12:00:00.000Z

data[].updatedAt string

Timestamp used for stale-edit protection. Preserve the server value when updating.

Example2026-01-15T12:00:00.000Z

data[].deletedAt string

ISO 8601 timestamp when the record was deleted, or null when it exists.

Examplenull

page object

Pagination metadata for the returned records, or the current page number when this endpoint uses numbered pages.

ShowHide 4 properties

page.limit number

Maximum number of records to return for this page.

Example1

page.hasMore boolean

Whether another page is available.

Examplefalse

page.nextCursor string

Opaque cursor for the next page, or null when there is no next page.

Examplenull

page.total number nullable

Total number of records that match the request.

Example1

Possible errors

400 Invalid request

Response headers

x-request-id string

Correlation identifier returned with every response for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error object

Error details returned for a failed request.

ShowHide 4 properties

error.code string

Stable machine-readable error or resource code.

Exampleinvalid_input

error.message string

Human-readable explanation of the result or error.

ExampleThe request could not be validated.

error.requestId string

Correlation identifier for support and request tracing.

Example550e8400-e29b-41d4-a716-446655440000

error.details object nullable

Additional structured details about the result or error.

ShowHide 1 property

error.details.issues object[]

Structured field issues returned when request validation fails.

ShowHide 3 properties

error.details.issues[].path string | number[]

Field path where the validation issue occurred.

One of: string alternative 1, number alternative 2

Example0 items

error.details.issues[].reason string

Machine-readable reason for the validation issue.

Allowed values: "expected_type", "required", "unexpected_property", "invalid_value", "invalid_json", "invalid_query", "unsupported_media_type", "body_too_large", "body_timeout", "conflicting_scope", "missing_header", "concurrency_required", "invalid_resource_id", "invalid_request"

Exampleinvalid_request

error.details.issues[].code string nullable

Stable machine-readable error or resource code.

Exampleinvalid_input

{
  "error": {
    "code": "invalid_input",
    "message": "The request could not be validated.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000",
    "details": {
      "issues": [
        {
          "path": [],
          "reason": "invalid_request"
        }
      ]
    }
  }
}

View raw OpenAPI operation

Use the machine-readable contract for client generation and payload validation.

Open OpenAPI contract ↗