> ## Documentation Index
> Fetch the complete documentation index at: https://learn.nexudus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Invoices

# List Invoices

Returns a paginated list of invoices for the currently authenticated customer. Supports filtering by payment status and whether to include credit notes.

## Authentication

This endpoint requires an authenticated customer session.

## Query Parameters

<ParamField query="paid" type="boolean">
  When `true`, returns only paid invoices. When `false`, returns only unpaid invoices. Omit to return all invoices.
</ParamField>

<ParamField query="creditNotes" type="boolean">
  When `true`, includes credit notes in the result set.
</ParamField>

<ParamField query="_shape" type="string">
  Comma-separated list of field paths to include in the response. When provided, only the
  specified fields are returned — useful for reducing payload size. Supports nested paths
  using dot notation. Example: `_shape=Records.InvoiceNumber,Records.TotalAmount,Records.Paid,TotalItems`.
</ParamField>

## Response

Returns an `ApiListResult<InvoicePreview>` object.

### Pagination

<ResponseField name="CurrentPage" type="number">
  The current page number.
</ResponseField>

<ResponseField name="CurrentPageSize" type="number">
  Number of records in the current page.
</ResponseField>

<ResponseField name="TotalItems" type="number">
  Total number of invoices matching the query.
</ResponseField>

<ResponseField name="TotalPages" type="number">
  Total number of available pages.
</ResponseField>

<ResponseField name="HasNextPage" type="boolean">
  Whether there is a next page.
</ResponseField>

<ResponseField name="HasPreviousPage" type="boolean">
  Whether there is a previous page.
</ResponseField>

### Records

Each item in `Records` follows the `InvoicePreview` shape. Key fields:

<ResponseField name="Id" type="number">
  Unique identifier of the invoice.
</ResponseField>

<ResponseField name="UniqueId" type="string">
  Globally unique identifier of the invoice.
</ResponseField>

<ResponseField name="InvoiceNumber" type="string">
  Human-readable invoice number as shown to the customer.
</ResponseField>

<ResponseField name="Paid" type="boolean">
  Whether the invoice has been fully paid.
</ResponseField>

<ResponseField name="PaidOn" type="string">
  ISO 8601 datetime when the invoice was paid (if applicable).
</ResponseField>

<ResponseField name="DueDate" type="string">
  ISO 8601 date the invoice is due.
</ResponseField>

<ResponseField name="Draft" type="boolean">
  Whether the invoice is still a draft.
</ResponseField>

<ResponseField name="CreditNote" type="boolean">
  Whether this document is a credit note rather than a standard invoice.
</ResponseField>

<ResponseField name="TotalAmount" type="number">
  Grand total of the invoice in the invoice currency.
</ResponseField>

<ResponseField name="DueAmount" type="number">
  Amount still outstanding.
</ResponseField>

<ResponseField name="TotalFormated" type="string">
  Pre-formatted total string (e.g. `"$199.00"`).
</ResponseField>

<ResponseField name="Currency" type="object">
  Currency object with fields: `Code`, `Name`, `Format`.
</ResponseField>

<ResponseField name="BusinessWebAddress" type="string">
  Web address of the location that issued the invoice. Used to construct PDF download links.
</ResponseField>

<ResponseField name="CreatedOn" type="string">
  ISO 8601 datetime when the invoice was created (local time).
</ResponseField>

## Example Response

```json theme={null}
{
  "Records": [
    {
      "Id": 12345,
      "UniqueId": "e9a3a3b8-8d3e-4b54-9f2d-0c82b2a8b9a1",
      "InvoiceNumber": "INV-2025-000123",
      "Paid": false,
      "PaidOn": null,
      "DueDate": "2025-10-01",
      "Draft": false,
      "CreditNote": false,
      "TotalAmount": 199.0,
      "DueAmount": 199.0,
      "TotalFormated": "$199.00",
      "Currency": { "Code": "USD", "Name": "US Dollar", "Format": "$0,0.00" },
      "BusinessWebAddress": "myspace.spaces.nexudus.com",
      "CreatedOn": "2025-09-28T10:15:00"
    }
  ],
  "CurrentPage": 1,
  "CurrentPageSize": 1,
  "TotalItems": 1,
  "TotalPages": 1,
  "HasNextPage": false,
  "HasPreviousPage": false
}
```

## Usage in Portal

This endpoint is used in two places:

1. **My Invoices section** – lists all invoices grouped by paid/unpaid status.

   * File: `src/views/user/activity/invoices/useInvoicesData.tsx`

2. **Onboarding action panel** – surfaces unpaid invoices to prompt the member to complete payment.
   * File: `src/views/user/dashboards/personal/components/OnBoarding/components/UnpaidInvoicesActionPanel.tsx`

### Typical integration pattern

```ts theme={null}
// From src/api/endpoints.ts
// endpoints.billing.invoices.list = (paid?: boolean, creditNotes?: boolean) => ({
//   url: `/api/public/billing/invoices/my?paid=${paid}&creditNotes=${creditNotes}`,
//   type: null as unknown as ApiListResult<InvoicePreview>,
// })

// Usage in React
const endpoint = endpoints.billing.invoices.list(false, false)
const { resource: invoices } = useData<typeof endpoint.type>(httpClient, endpoint.url)
```

## Related Endpoints

* `GET /api/public/billing/invoices/{invoiceId}` – Retrieve a single invoice by ID
* `GET /api/public/billing/invoices/{invoiceId}/pdf` – Download invoice as PDF

## Error Responses

<ResponseField name="401 Unauthorized" type="error">
  The current user is not authenticated.
</ResponseField>