# List invoices

Returns a **paginated** list of invoices for the practice identified by
`X-Practice-Id`. Results are ordered by **creation time**, most recent created first
(`created_at` descending), then by `id` descending for a stable sort.
Optional query parameters allow filtering results by patient, site,
create and update date ranges, and if the invoice has been paid.
When `is_paid` is `true`, results are restricted to invoices that have been paid.
When `false`, results are restricted to invoices that have not been paid.
When omitted, all invoices are returned.
**Date range.** Optional query parameters `created_date_from` and `created_date_to` filter by creation date,
while `updated_date_from` and `updated_date_to` filter by update date. Both ends are inclusive.
Use `limit` and the `meta.cursor` value from the response to retrieve further pages.

Endpoint: GET /invoices
Version: 2026-01-01
Security: oauth2

## Security:

  - `oauth2` (unknown)
    oauth2 scopes: invoice:read

## Query parameters:

  - `limit` (integer)
    Maximum number of records to return per page.

  - `cursor` (string)
    Cursor reference to the next page of records.

  - `site_id` (string)
    Filter records to those occurring at the specified site. The value should be a UUID corresponding to a site within the practice.

  - `created_date_from` (string)
    Inclusive start of a created date range filter. Calendar date only (`YYYY-MM-DD`).
Use together with `created_date_to` for explicit date range control.
- When used together with `created_date_to`, the range between the two values must not exceed 90 days.
- When used without `created_date_to`, returns records from `created_date_from` up to 90 days later
(or up to the current date-time if it is earlier).

  - `created_date_to` (string)
    Inclusive end of a created date range filter. Calendar date only (`YYYY-MM-DD`).
Use together with `created_date_from` for explicit date range control.
- When used together with `created_date_from`, the range between the two values must not exceed 90 days.
- When used without `created_date_from`, returns records from 90 days before `created_date_to` (or from the
earliest available date if less than 90 days of data exists) up to `created_date_to`.

  - `updated_date_from` (string)
    Inclusive start of an updated date range filter. Calendar date only (`YYYY-MM-DD`).
Use together with `updated_date_to` for explicit date range control.
- When used together with `updated_date_to`, the range between the two values must not exceed 90 days.
- When used without `updated_date_to`, returns records from `updated_date_from` up to 90 days later
(or up to the current date-time if it is earlier).

  - `updated_date_to` (string)
    Inclusive end of an updated date range filter. Calendar date only (`YYYY-MM-DD`).
Use together with `updated_date_from` for explicit date range control.
- When used together with `updated_date_from`, the range between the two values must not exceed 90 days.
- When used without `updated_date_from`, returns records from 90 days before `updated_date_to` (or from the
earliest available date if less than 90 days of data exists) up to `updated_date_to`.

  - `patient_id` (string)
    Filter invoices to those associated with the specified patient. The value should be a UUID corresponding to a patient within the practice.

  - `is_paid` (boolean)
    Filter invoices to those that have been paid or unpaid.

## Header parameters:

  - `X-Practice-Id` (string, required)
    UUID of the **practice** in whose context the request is executed. The API
uses this to resolve data the caller is permitted to access for that practice.

## Response 200:

  - `200` (unknown)
    The list of invoices.

## Response 200 fields (application/json):

  - `data` (array, required)
    List of invoices.

  - `data.created_at` (string, required)
    When the resource was created (UTC, ISO 8601) in UTC.
    Example: 2024-01-15T09:30:00Z

  - `data.updated_at` (string, required)
    When the resource was last updated (UTC, ISO 8601) in UTC.
    Example: 2024-06-20T14:05:22Z

  - `data.id` (string, required)
    Unique identifier for the invoice.
    Example: 123e4567-e89b-12d3-a456-426614174000

  - `data.patient_id` (string, required)
    Unique identifier for the patient associated with this invoice.
    Example: 550e8400-e29b-41d4-a716-446655440004

  - `data.site_id` (string, required)
    Unique identifier for the site associated with this invoice.
    Example: 7c9e6679-7425-40de-944b-e07fc1f90ae7

  - `data.reference` (string, required)
    Human readable invoice identifier.
    Example: 00103

  - `data.invoice_amount` (number, required)
    Total invoice amount.
    Example: 150

  - `data.invoice_amount_outstanding` (number, required)
    Total amount still owed for this invoice.
    Example: 10

  - `data.patient_owed_amount` (number, required)
    Amount the patient owes for this invoice.
    Example: 15

  - `data.insurance_owed_amount` (number, required)
    Amount the insurance provider owes for this invoice.
    Example: 20

  - `data.insurance_paid_amount` (number, required)
    Amount the insurance provider has paid for this invoice.
    Example: 30

  - `data.pending_payments_amount` (number, required)
    Total pending payments by the insurance provider for this invoice.
    Example: 20

  - `data.tax_amount` (number, required)
    Total tax amount for this invoice.
    Example: 20

  - `data.discount_amount` (number, required)
    Total discount amount for this invoice.
    Example: 20

  - `data.is_paid` (boolean, required)
    Whether the invoice has been paid or not.
    Example: false

  - `data.paid_on` (string)
    When the invoice was paid on.
    Example: 2019-05-14

  - `data.is_editable` (boolean, required)
    Whether the invoice can be edited or not.
    Example: false

  - `data.created_by` (string)
    Identifier of the user who created the invoice, if applicable.
    Example: 550e8400-e29b-41d4-a716-446655440005

  - `meta` (object, required)
    Cursor-based pagination metadata. When an operation supports paging, pass `cursor` from this object on a subsequent request to continue after the current page.

  - `meta.cursor` (string, required)
    Opaque pagination cursor for the next page. Clients should treat this value as an opaque token.
    Example: eyJjdXJzb3IiOiJuZXh0In0

## Response 400:

  - `400` (unknown)
    Malformed Request ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 400 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 401:

  - `401` (unknown)
    Unauthorized - Provide proof of identity ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 401 fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 4XX:

  - `4XX` (unknown)
    User Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 4XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 5XX:

  - `5XX` (unknown)
    Server Error ([ProblemDetails](https://tools.ietf.org/html/rfc7807))

## Response 5XX fields (application/problem+json):

  - `type` (string)
    A URI reference [[RFC3986](https://tools.ietf.org/html/rfc3986)] that
identifies the problem type. It should provide human-readable
documentation for the problem type. When this member is not present, its
value is assumed to be "about:blank".
    Example: https://httpstatuses.io/400

  - `title` (string)
    A short, human-readable summary of the problem type. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.
    Example: Bad Request

  - `status` (integer)
    The HTTP status code.
    Example: 400

  - `detail` (string)
    A human-readable explanation specific to this occurrence of the problem.
    Example: Missing required field 'address'

  - `instance` (string)
    A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if de-referenced.
    Example: /v2/sites

## Response 200 examples:

  - `First page of invoices` (unknown)
    Paginated list with cursor for the next page.

## Response 400 examples:

  - `Malformed or invalid request` (unknown)
    RFC 7807 problem details when validation fails (e.g. missing required field).

## Response 401 examples:

  - `Missing or invalid credentials` (unknown)
    RFC 7807 problem details when the caller is not authenticated.

## Response 4XX examples:

  - `Generic client error response` (unknown)
    RFC 7807 problem details for a generic client error (e.g. conflict, unsupported media type).

## Response 5XX examples:

  - `Unexpected server error` (unknown)
    RFC 7807 problem details for an internal failure.