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

# List Invoices

> Retrieve a paginated list of invoices with optional filtering and sorting

Retrieves a paginated list of all invoices. You can filter and sort the results using query parameters.

## Query Parameters

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

<ParamField query="limit" type="integer" default="10">
  The number of invoices to return per page. Must be one of: `5`, `10`, `25`, `50`, or `100`. Values exceeding `100` are capped automatically.
</ParamField>

<ParamField query="filters" type="string">
  A JSON-encoded array of filter objects. Each filter object has the following properties:

  <Expandable title="Filter Object">
    <ParamField body="field" type="string" required>
      The field to filter on. Supported fields:

      | Field             | Operators          | Description                                                         |
      | ----------------- | ------------------ | ------------------------------------------------------------------- |
      | `status`          | `eq`, `in`         | Invoice status (e.g. `draft`, `upcoming`, `issued`, `paid`, `void`) |
      | `account_id`      | `eq`               | The account ID associated with the invoice                          |
      | `subscription_id` | `eq`               | The subscription ID associated with the invoice                     |
      | `autopay`         | `eq`               | Whether the invoice is set to auto-pay (`true` or `false`)          |
      | `invoicing_date`  | `eq`, `gte`, `lte` | The invoicing date (ISO 8601 format)                                |
      | `issue_date`      | `eq`, `gte`, `lte` | The issue date (ISO 8601 format)                                    |
      | `due_date`        | `eq`, `gte`, `lte` | The due date (ISO 8601 format)                                      |
      | `paid_date`       | `eq`, `gte`, `lte` | The paid date (ISO 8601 format)                                     |
      | `tag_ids`         | `in`               | Tag IDs associated with the invoice                                 |
    </ParamField>

    <ParamField body="operator" type="string" required>
      The comparison operator.

      | Operator | Description                                 |
      | -------- | ------------------------------------------- |
      | `eq`     | Exact match                                 |
      | `in`     | Matches any value in a comma-separated list |
      | `gte`    | Greater than or equal to (date fields)      |
      | `lte`    | Less than or equal to (date fields)         |
    </ParamField>

    <ParamField body="value" type="string" required>
      The value to match against. For the `in` operator, use comma-separated values. For date operators, use ISO 8601 format.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField query="sort" type="string">
  Sort specification in `field:order` format. Order is either `asc` (ascending) or `desc` (descending).

  Sortable fields: `invoicing_date`, `issue_date`, `due_date`, `paid_date`, `account_name`, `status`.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://api.alguna.io/invoices?page=1&limit=25" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with filters and sort) theme={null}
  curl -G "https://api.alguna.io/invoices" \
    -H "Authorization: Bearer YOUR_API_KEY" \
    --data-urlencode 'page=1' \
    --data-urlencode 'limit=10' \
    --data-urlencode 'filters=[{"field":"status","operator":"in","value":"issued,paid"},{"field":"due_date","operator":"gte","value":"2024-01-01T00:00:00Z"}]' \
    --data-urlencode 'sort=due_date:desc'
  ```

  ```javascript Node.js theme={null}
  const invoices = await alguna.invoices.list({
    page: 1,
    limit: 25,
    filters: [
      { field: "status", operator: "in", value: "issued,paid" },
      { field: "due_date", operator: "gte", value: "2024-01-01T00:00:00Z" }
    ],
    sort: "due_date:desc"
  });
  ```
</RequestExample>

## Response

<Snippet file="list-invoices.mdx" />

<ResponseField name="items" type="array">
  List of invoice objects.

  <Expandable title="Invoice Object">
    <ResponseField name="id" type="string">
      The Alguna ID of the invoice.
    </ResponseField>

    <ResponseField name="accountId" type="string">
      The Alguna ID of the account associated with the invoice.
    </ResponseField>

    <ResponseField name="currency" type="string">
      The ISO 4217 currency in which the invoice is billed.
    </ResponseField>

    <ResponseField name="description" type="string">
      The description or memo for the invoice.
    </ResponseField>

    <ResponseField name="billingPeriodStart" type="string">
      The start date of the billing period for the invoice (RFC 3339 timestamp).
    </ResponseField>

    <ResponseField name="billingPeriodEnd" type="string">
      The end date of the billing period for the invoice (RFC 3339 timestamp).
    </ResponseField>

    <ResponseField name="status" type="string">
      The status of the invoice. For more info on invoice statuses see the [invoice status](/docs/invoices/invoicing-config) guide.
    </ResponseField>

    <ResponseField name="total" type="string">
      The total amount of the invoice as a decimal string e.g., "200.00".
    </ResponseField>

    <ResponseField name="billingPeriod" type="string">
      The formatted billing period for the invoice.
    </ResponseField>

    <ResponseField name="createdAt" type="datetime">
      The date and time at which the invoice was created.
    </ResponseField>

    <ResponseField name="updatedAt" type="datetime">
      The date and time at which the invoice was last updated.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pageCount" type="integer">
  Total number of pages available based on the current limit.
</ResponseField>

<ResponseField name="limit" type="integer">
  The number of items per page used for this request.
</ResponseField>