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

# list_invoices — Filtered, paginated invoice list

> Reference for the list_invoices MCP tool. Query invoices by status, contact, due date, and issue date with cursor-based pagination.

The `list_invoices` tool returns a filtered, paginated list of invoices for a single organization. Use it to track receivables, find overdue invoices, or review what a customer has been billed. Every request must include `intent` and `organizationId`, and the token must carry the `invoices.read` scope.

> [!NOTE]
>
> Receivables tools require the organization to have invoicing set up in Relay. If it does not, the tool returns an error instead of data.

## Scope

Required OAuth scope: `invoices.read`

## Input

**organizationId** `string` *required*

The organization to query. Must be one of the organizations the token can access.

**status** `string[]`

Filter to one or more statuses. Allowed values: `DRAFT`, `UNSENT`, `SENT`, `PROCESSING`, `PAID`, `OVERDUE`, `CANCELLED`, `SCHEDULED`, `PAYMENT_FAILED`.

**contactId** `string`

Filter to invoices billed to a single contact.

**dueAfter** `string`

Lower bound for `dueDate`, in `YYYY-MM-DD` format.

**dueBefore** `string`

Upper bound for `dueDate`, in `YYYY-MM-DD` format.

**issuedAfter** `string`

Lower bound for the issue date, in `YYYY-MM-DD` format.

**issuedBefore** `string`

Upper bound for the issue date, in `YYYY-MM-DD` format.

**cursor** `string`

Opaque pagination cursor from a previous response. Keep the same `pageSize` and filters when following cursors. Never parse, edit, or reuse a cursor across different filter sets.

**pageSize** `integer`

Number of results per page. Must be between 1 and 100. Defaults to 50.

**intent** `string` *required*

What the user asked for and why this call serves it, in 1 to 500 characters. Required on every tool call. See [Common tool arguments](https://mcp.docs.relayfi.com/concepts/transport.md#common-tool-arguments).

## Output

**data** `Invoice[]` *required*

Array of invoices matching the filters.

**Invoice**

**id** `string` *required*

Unique invoice identifier. Use this value as `invoiceId`.

**organizationId** `string` *required*

Organization the invoice belongs to.

**status** `string` *required*

Invoice status. Values: `DRAFT`, `UNSENT`, `SENT`, `PROCESSING`, `PAID`, `OVERDUE`, `CANCELLED`, `SCHEDULED`, `PAYMENT_FAILED`.

**invoiceNumber** `string` *required*

Invoice number shown to the payer.

**contactId** `string` *required*

Contact the invoice is billed to. Pass to `get_contact` for details.

**memo** `string` *required*

Memo shown on the invoice.

**dueDate** `string` *required*

Due date in `YYYY-MM-DD` format.

**lineItems** `LineItem[]` *required*

Line items on the invoice.

**LineItem**

**description** `string` *required*

Description of the line item.

**quantity** `number` *required*

Quantity billed.

**unitPrice** `Money` *required*

Unit price as a [Money](https://mcp.docs.relayfi.com/concepts/results.md#money) object, rounded to cents.

**unitPriceDecimal** `string` *required*

Exact unit price as a decimal string.

**total** `Money` *required*

Line total.

**catalogItemId** `string | null` *required*

Catalog item the line was created from, if any.

**taxes** `object[]` *required*

Taxes applied to this line.

**discounts** `Discount[]` *required*

Discounts applied to this line.

**Discount**

**type** `string` *required*

Discount type. Values: `PERCENTAGE`, `FIXED`.

**percentage** `number`

Percentage off. Present when `type` is `PERCENTAGE`.

**amount** `Money`

Fixed amount off as a [Money](https://mcp.docs.relayfi.com/concepts/results.md#money) object. Present when `type` is `FIXED`.

**discounts** `Discount[]` *required*

Discounts applied to the whole invoice.

**Discount**

**type** `string` *required*

Discount type. Values: `PERCENTAGE`, `FIXED`.

**percentage** `number`

Percentage off. Present when `type` is `PERCENTAGE`.

**amount** `Money`

Fixed amount off as a [Money](https://mcp.docs.relayfi.com/concepts/results.md#money) object. Present when `type` is `FIXED`.

**lineItemTotal** `Money` *required*

Sum of line totals before invoice-level discounts and taxes.

**discountTotal** `Money` *required*

Total of all discounts.

**taxTotal** `Money` *required*

Total of all taxes.

**grandTotal** `Money` *required*

Amount due on the invoice.

**issuedAt** `string | null` *required*

Timestamp when the invoice was issued, in RFC 3339 format.

**sentAt** `string | null` *required*

Timestamp when the invoice was sent, in RFC 3339 format.

**paidAt** `string | null` *required*

Timestamp when the invoice was paid, in RFC 3339 format.

**createdAt** `string` *required*

Timestamp when the invoice was created, in RFC 3339 format.

**updatedAt** `string` *required*

Timestamp when the invoice was last updated, in RFC 3339 format.

**editUrl** `string` *required*

Link that opens the invoice in Relay. Always present. Pass it to the user exactly as returned.

**portalUrl** `string | null` *required*

Payer-facing link to view and pay the invoice. `null` for `DRAFT` invoices and may be `null` for some older invoices.

**pagination** `object` *required*

Cursor-based pagination metadata.

**Pagination**

**hasNextPage** `boolean` *required*

Whether more results are available.

**pageSize** `integer` *required*

Number of results in this page.

**nextCursor** `string`

Opaque cursor to fetch the next page. Present only when `hasNextPage` is `true`.

## Example

```json Request theme={null}
{
  "jsonrpc": "2.0",
  "id": 14,
  "method": "tools/call",
  "params": {
    "name": "list_invoices",
    "arguments": {
      "intent": "User asked which invoices are still unpaid this month.",
      "organizationId": "org_1",
      "status": [
        "SENT",
        "OVERDUE"
      ],
      "dueBefore": "2026-10-31",
      "pageSize": 10
    }
  }
}
```

```json Response theme={null}
{
  "jsonrpc": "2.0",
  "id": 14,
  "result": {
    "structuredContent": {
      "data": [
        {
          "id": "inv_1",
          "organizationId": "org_1",
          "status": "SENT",
          "invoiceNumber": "INV-0042",
          "contactId": "ct_1",
          "memo": "September consulting",
          "dueDate": "2026-10-31",
          "lineItems": [
            {
              "description": "Consulting hour",
              "quantity": 10,
              "unitPrice": {
                "cents": 15000,
                "display": "150.00",
                "currency": "USD"
              },
              "unitPriceDecimal": "150.00",
              "total": {
                "cents": 150000,
                "display": "1,500.00",
                "currency": "USD"
              },
              "catalogItemId": "item_1",
              "taxes": [],
              "discounts": []
            }
          ],
          "discounts": [
            {
              "type": "PERCENTAGE",
              "percentage": 10
            }
          ],
          "lineItemTotal": {
            "cents": 150000,
            "display": "1,500.00",
            "currency": "USD"
          },
          "discountTotal": {
            "cents": 15000,
            "display": "150.00",
            "currency": "USD"
          },
          "taxTotal": {
            "cents": 0,
            "display": "0.00",
            "currency": "USD"
          },
          "grandTotal": {
            "cents": 135000,
            "display": "1,350.00",
            "currency": "USD"
          },
          "issuedAt": "2026-10-01T14:00:00.000Z",
          "sentAt": "2026-10-01T14:05:00.000Z",
          "paidAt": null,
          "createdAt": "2026-09-30T18:12:00.000Z",
          "updatedAt": "2026-10-01T14:05:00.000Z",
          "editUrl": "https://app.relayfi.com/<invoice-link>",
          "portalUrl": "https://app.relayfi.com/<payer-link>"
        }
      ],
      "pagination": {
        "hasNextPage": false,
        "pageSize": 10
      }
    }
  }
}
```

## Notes

* Always pass `editUrl` to the user exactly as returned. Do not construct or modify invoice links.
* `portalUrl` is the payer-facing link. It is `null` for `DRAFT` invoices and may be `null` for some older invoices.
* All totals are Money objects. `unitPriceDecimal` on each line item carries the exact unit price.
* Follow `nextCursor` until `hasNextPage` is `false`. Keep the same `pageSize` and filters on every page.

> [card] [get\_invoice](https://mcp.docs.relayfi.com/tools/get-invoice.md)
>
> Fetch a single invoice by ID.

> [card] [Result conventions](https://mcp.docs.relayfi.com/concepts/results.md)
>
> Learn how pagination, Money objects, and dual-channel output work across all tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.