# List invoices

**Retrieve invoices with comprehensive filtering and financial data**
This endpoint delivers complete invoice management functionality with:
- Advanced pagination for large invoice datasets
- Multi-dimensional filtering (client, status, date ranges)
- Integration with AR transactions for complete financial context
- Tax, interest, and payment status tracking
- Client relationship data for each invoice
- Aggregate counting for reporting and analytics

**Key Financial Features:**
- Invoice status tracking (PENDING, PAID, OVERDUE, POSTED, etc.)
- Tax and interest calculations included
- Due date monitoring for collections management
- AR transaction linkage for payment reconciliation
- Amount and allocation tracking for financial reporting

**Filtering Capabilities:**
- Client-specific invoice retrieval
- Status-based filtering for workflow management
- Date range queries for period reporting
- Sorting by creation date or transaction date

**Business Applications:**
- Accounts receivable management and aging reports
- Client billing history and statement generation
- Collections management and overdue tracking
- Financial reporting and revenue recognition
- Payment reconciliation and allocation tracking

**Real Example:**

```bash
curl --location 'https://{{host}}/v1/invoices' \
--header 'Authorization: bearer {{token}} \
--header 'Content-Type: application/json' \
--data '{
  "pageSize": 25,
  "page": 0
}'
```

Endpoint: POST /gql/v1/invoices
Version: 1.0.0
Security: BearerAuth

## Request fields (application/json):

  - `pageSize` (integer)
    Maximum number of invoice records to return
    Example: 25

  - `page` (integer)
    Page number for pagination (0-based)
    Example: 0

  - `clientId` (integer)
    Filter invoices by specific client ID
    Example: 7720

  - `status` (string)
    Filter by invoice status
    Enum: "PENDING", "POSTED", "PAID", "OVERDUE", "CANCELLED", "DRAFT"

  - `startDate` (string)
    Start date for invoice date range filter
    Example: 1990-01-01T00:00:00

  - `endDate` (string)
    End date for invoice date range filter
    Example: 2024-12-31T23:59:59

  - `sortOrder` (string)
    Sort order for invoice dates
    Enum: "asc", "desc"

## Response 200 fields (application/json):

  - `invoices` (array)

  - `invoices.arTranId` (integer)
    Invoice identifier (equal to the AR transaction id)
    Example: 125890

  - `invoices.invoiceNumber` (string)
    Unique invoice number for client reference
    Example: INV-2024-4850

  - `invoices.dueDate` (string)
    Invoice payment due date
    Example: 2024-04-24T05:00:00

  - `invoices.status` (string)
    Current invoice status
    Example: POSTED

  - `invoices.tax` (number)
    Tax amount charged on invoice
    Example: 0

  - `invoices.interest` (number)
    Interest charges applied to invoice
    Example: 0

  - `invoices.description` (string)
    Additional invoice description or notes
    Example: null

  - `invoices.createdAt` (string)
    Invoice record creation timestamp
    Example: 2024-05-12T22:50:20.595961+00:00

  - `invoices.updatedAt` (string)
    Invoice record last update timestamp
    Example: 2024-05-12T22:50:20.595961+00:00

  - `invoices.ar_tran` (object)
    Associated AR transaction details

  - `invoices.ar_tran.id` (integer)
    Example: 125890

  - `invoices.ar_tran.pmsRef` (string)
    Practice management system reference
    Example: 240815

  - `invoices.ar_tran.transactionDate` (string)
    Transaction date
    Example: 2024-03-22T05:00:00

  - `invoices.ar_tran.amount` (number)
    Transaction amount
    Example: 4250

  - `invoices.ar_tran.allocated` (number)
    Allocated amount
    Example: 4250

  - `invoices.ar_tran.clientId` (integer)
    Client identifier
    Example: 7720

  - `total` (object)

  - `total.aggregate` (object)

  - `total.aggregate.count` (integer)
    Total number of invoices
    Example: 94

## Response 400 fields (application/json):

  - `error` (string)

  - `code` (string)

## Response 401 fields (application/json):

  - `error` (string)

  - `code` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `code` (string)