> ## 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.

# Search Invoices

> Search and list Invoice records with filtering, sorting, and pagination.

An **Invoice** represents a bill issued by Nexudus to the operator (the business running the coworking space). Invoices are generated automatically by the billing engine or can be created manually via the API.

Each invoice captures a snapshot of the billing details at issuance time — bill-to address, currency, tax amounts, and line items. Once issued, the invoice record is immutable with respect to these captured values; changes to the underlying financial accounts, products or customer details do not retroactively update existing invoices.

Invoices support `list`, `get`, and `create` operations. They cannot be updated or deleted through the API.

## Authentication

<Note>
  This endpoint requires OAuth2 authentication. Include a valid bearer token in the `Authorization` header.
  The authenticated user must be a full unrestricted administrator or have the **`Invoice-List`** role.
</Note>

## Query Parameters

### Pagination & Sorting

<ParamField query="page" type="integer" default="1">
  The page number to retrieve.
</ParamField>

<ParamField query="size" type="integer" default="25">
  The number of records per page.
</ParamField>

<ParamField query="orderBy" type="string">
  The property name to sort results by (e.g. `Name`, `CreatedOn`).
</ParamField>

<ParamField query="dir" type="integer">
  Sort direction. `0` for ascending, `1` for descending.
</ParamField>

### Filters

<ParamField query="Invoice_Business" type="integer">
  Filter by Business Id.
</ParamField>

<ParamField query="Invoice_InvoiceNumber" type="string">
  Filter by unique sequential invoice number assigned at issuance (e.g. INV-00042).
</ParamField>

<ParamField query="Invoice_BillToName" type="string">
  Filter by name of the person or organisation being billed, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToAddress" type="string">
  Filter by billing street address, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToCity" type="string">
  Filter by billing city, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToTaxIDNumber" type="string">
  Filter by tax identification number (VAT/GST/EIN) of the billed party, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToPostCode" type="string">
  Filter by billing postal/ZIP code, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToPhone" type="string">
  Filter by billing phone number, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToFax" type="string">
  Filter by billing fax number, captured at invoice time.
</ParamField>

<ParamField query="Invoice_BillToCountry" type="integer">
  Filter by Bill To Country Id.
</ParamField>

<ParamField query="Invoice_BillToCountry_Name" type="string">
  Filter by display name of the billing country (read-only, resolved from BillToCountryId).
</ParamField>

<ParamField query="Invoice_Description" type="string">
  Filter by free-text description or notes for this invoice.
</ParamField>

<ParamField query="Invoice_DiscountAmount" type="number">
  Filter by total discount applied to the invoice, in the invoice currency.
</ParamField>

<ParamField query="Invoice_DueDate" type="string">
  Filter by date by which payment is expected.
</ParamField>

<ParamField query="Invoice_InvoiceFromDate" type="string">
  Filter by start date of the billing period covered by this invoice.
</ParamField>

<ParamField query="Invoice_InvoiceToDate" type="string">
  Filter by end date of the billing period covered by this invoice.
</ParamField>

<ParamField query="Invoice_SubscriptionAmount" type="number">
  Filter by portion of the total that corresponds to recurring subscription charges.
</ParamField>

<ParamField query="Invoice_ResellerAmount" type="number">
  Filter by portion of the total attributed to the reseller (partner) channel.
</ParamField>

<ParamField query="Invoice_TotalAmount" type="number">
  Filter by grand total of the invoice including all line items, taxes, and discounts.
</ParamField>

<ParamField query="Invoice_Currency" type="integer">
  Filter by Currency Id.
</ParamField>

<ParamField query="Invoice_Currency_Code" type="string">
  Filter by iSO 4217 currency code (e.g. USD, EUR), resolved from CurrencyId.
</ParamField>

<ParamField query="Invoice_TaxAmount" type="number">
  Filter by total tax amount calculated for the invoice.
</ParamField>

<ParamField query="Invoice_Paid" type="boolean">
  Filter by whether the invoice has been fully paid.
</ParamField>

<ParamField query="Invoice_PaidOn" type="string">
  Filter by date and time when full payment was recorded.
</ParamField>

<ParamField query="Invoice_CustomData" type="string">
  Filter by arbitrary JSON or text blob for storing integration-specific metadata.
</ParamField>

<ParamField query="Invoice_PaymentAttemptsCount" type="integer">
  Filter by number of automatic payment collection attempts made for this invoice.
</ParamField>

### Range Filters

<ParamField query="from_Invoice_DiscountAmount" type="number">
  Filter by total discount applied to the invoice, in the invoice currency greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_DiscountAmount" type="number">
  Filter by total discount applied to the invoice, in the invoice currency less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_DueDate" type="string">
  Filter by date by which payment is expected greater than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_DueDate" type="string">
  Filter by date by which payment is expected less than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_Invoice_InvoiceFromDate" type="string">
  Filter by start date of the billing period covered by this invoice greater than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_InvoiceFromDate" type="string">
  Filter by start date of the billing period covered by this invoice less than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_Invoice_InvoiceToDate" type="string">
  Filter by end date of the billing period covered by this invoice greater than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_InvoiceToDate" type="string">
  Filter by end date of the billing period covered by this invoice less than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_Invoice_SubscriptionAmount" type="number">
  Filter by portion of the total that corresponds to recurring subscription charges greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_SubscriptionAmount" type="number">
  Filter by portion of the total that corresponds to recurring subscription charges less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_ResellerAmount" type="number">
  Filter by portion of the total attributed to the reseller (partner) channel greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_ResellerAmount" type="number">
  Filter by portion of the total attributed to the reseller (partner) channel less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_TotalAmount" type="number">
  Filter by grand total of the invoice including all line items, taxes, and discounts greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_TotalAmount" type="number">
  Filter by grand total of the invoice including all line items, taxes, and discounts less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_TaxAmount" type="number">
  Filter by total tax amount calculated for the invoice greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_TaxAmount" type="number">
  Filter by total tax amount calculated for the invoice less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_PaidOn" type="string">
  Filter by date and time when full payment was recorded greater than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_PaidOn" type="string">
  Filter by date and time when full payment was recorded less than or equal to this value. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_Invoice_PaymentAttemptsCount" type="integer">
  Filter by number of automatic payment collection attempts made for this invoice greater than or equal to this value.
</ParamField>

<ParamField query="to_Invoice_PaymentAttemptsCount" type="integer">
  Filter by number of automatic payment collection attempts made for this invoice less than or equal to this value.
</ParamField>

<ParamField query="from_Invoice_CreatedOn" type="string">
  Filter records created on or after this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_CreatedOn" type="string">
  Filter records created on or before this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="from_Invoice_UpdatedOn" type="string">
  Filter records updated on or after this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

<ParamField query="to_Invoice_UpdatedOn" type="string">
  Filter records updated on or before this date. Format: `YYYY-MM-DDTHH:mm`.
</ParamField>

## Code Examples

### Simple listing

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/billing/invoices?page=1&size=15&orderBy=InvoiceNumber&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/billing/invoices?' + new URLSearchParams({
      page: 1,
      size: 15,
      orderBy: 'InvoiceNumber',
      dir: 1 // Ascending
    }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/billing/invoices',
      params={
          'page': 1,
          'size': 15,
          'orderBy': 'InvoiceNumber',
          'dir': 0 // Ascending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Filtering by InvoiceNumber

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/billing/invoices?Invoice_InvoiceNumber=example-value&orderBy=InvoiceNumber&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/billing/invoices?' + new URLSearchParams({
      Invoice_InvoiceNumber: 'example-value',
      orderBy: 'InvoiceNumber',
      dir: 1
    }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/billing/invoices',
      params={
          'Invoice_InvoiceNumber': 'example-value',
          'orderBy': 'InvoiceNumber',
          'dir': 0 // Ascending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

### Range filters

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET \
    "https://spaces.nexudus.com/api/billing/invoices?from_Invoice_UpdatedOn=2025-01-01T00:00&to_Invoice_UpdatedOn=2025-12-31T23:59&orderBy=UpdatedOn&dir=0" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://spaces.nexudus.com/api/billing/invoices?' + new URLSearchParams({
      from_Invoice_UpdatedOn: '2025-01-01T00:00',
      to_Invoice_UpdatedOn: '2025-12-31T23:59',
      orderBy: 'UpdatedOn',
      dir: 1 // Descending
     }),
    {
      headers: {
        'Authorization': 'Bearer YOUR_TOKEN'
      }
    }
  );

  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://spaces.nexudus.com/api/billing/invoices',
      params={
          'from_Invoice_UpdatedOn': '2025-01-01T00:00',
          'to_Invoice_UpdatedOn': '2025-12-31T23:59',
          'orderBy': 'UpdatedOn',
          'dir': 1 // Descending
      },
      headers={
          'Authorization': 'Bearer YOUR_TOKEN'
      }
  )

  data = response.json()
  ```
</CodeGroup>

## Response

### 200

<ResponseField name="Records" type="Invoice[]">
  The list of Invoice records matching the query. See the [Get one Invoice](/rest-api/billing/get-invoices-by-id) endpoint for the full list of properties returned for each record.
</ResponseField>

<Warning>
  **Partial records** — The listing endpoint returns a summary representation of each Invoice. The following fields are **not populated** in the `Records[]` response: `BillToAddress`, `BillToCity`, `BillToTaxIDNumber`, `BillToPostCode`, `BillToPhone`, `BillToFax`.

  To get all fields, fetch the full record using the [Get one Invoice](/rest-api/billing/get-invoices-by-id) endpoint.

  **Important for updates:** When updating a record via `PUT`, always retrieve the full record with a `GET` request first, apply your changes to that complete data, and then send the updated record. Do not use data from a listing response as the base for a `PUT` request, as missing fields may be unintentionally cleared.
</Warning>

<ResponseField name="CurrentPage" type="integer">
  Current page number.
</ResponseField>

<ResponseField name="CurrentPageSize" type="integer">
  Number of records per page.
</ResponseField>

<ResponseField name="CurrentOrderField" type="string">
  The field used for sorting.
</ResponseField>

<ResponseField name="CurrentSortDirection" type="integer">
  The sort direction (`0` = ascending, `1` = descending).
</ResponseField>

<ResponseField name="FirstItem" type="integer">
  Index of the first item on the current page.
</ResponseField>

<ResponseField name="LastItem" type="integer">
  Index of the last item on the current page.
</ResponseField>

<ResponseField name="TotalItems" type="integer">
  Total number of matching records across all pages.
</ResponseField>

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

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

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

```json Example Response theme={null}
{
  "Records": [
    {
      "BusinessId": 0,
      "InvoiceNumber": "",
      "BillToName": "",
      "BillToCountryId": 0,
      "BillToCountryName": null,
      "Description": null,
      "DiscountAmount": 0,
      "DueDate": null,
      "InvoiceFromDate": null,
      "InvoiceToDate": null,
      "SubscriptionAmount": 0,
      "ResellerAmount": 0,
      "TotalAmount": 0,
      "CurrencyId": 0,
      "CurrencyCode": null,
      "TaxAmount": 0,
      "Paid": false,
      "PaidOn": null,
      "CustomData": null,
      "PaymentAttemptsCount": 0,
      "Id": 87654321,
      "UpdatedOn": "2025-01-15T10:30:00Z",
      "CreatedOn": "2025-01-10T08:00:00Z",
      "UniqueId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "UpdatedBy": "admin@example.com",
      "IsNew": false,
      "SystemId": null,
      "ToStringText": "Invoice Example",
      "LocalizationDetails": null,
      "CustomFields": null
    }
  ],
  "CurrentPageSize": 15,
  "CurrentPage": 1,
  "CurrentOrderField": "InvoiceNumber",
  "CurrentSortDirection": 1,
  "FirstItem": 1,
  "HasNextPage": false,
  "HasPreviousPage": false,
  "LastItem": 1,
  "PageNumber": 1,
  "PageSize": 15,
  "TotalItems": 1,
  "TotalPages": 1
}
```