list_invoices — Filtered, paginated invoice list

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.

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

string

required

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

string[]

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

string

Filter to invoices billed to a single contact.

string

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

string

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

string

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

string

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

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.

integer

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

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.

Output

Invoice[]

required

Array of invoices matching the filters.

Show Invoice

string

required

Unique invoice identifier. Use this value as invoiceId.

string

required

Organization the invoice belongs to.

string

required

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

string

required

Invoice number shown to the payer.

string

required

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

string

required

Memo shown on the invoice.

string

required

Due date in YYYY-MM-DD format.

LineItem[]

required

Line items on the invoice.

Show LineItem

string

required

Description of the line item.

number

required

Quantity billed.

Money

required

Unit price as a Money object, rounded to cents.

string

required

Exact unit price as a decimal string.

Money

required

Line total.

string | null

required

Catalog item the line was created from, if any.

object[]

required

Taxes applied to this line.

Discount[]

required

Discounts applied to this line.

Show Discount

string

required

Discount type. Values: PERCENTAGE, FIXED.

number

Percentage off. Present when type is PERCENTAGE.

Money

Fixed amount off as a Money object. Present when type is FIXED.

Discount[]

required

Discounts applied to the whole invoice.

Show Discount

string

required

Discount type. Values: PERCENTAGE, FIXED.

number

Percentage off. Present when type is PERCENTAGE.

Money

Fixed amount off as a Money object. Present when type is FIXED.

Money

required

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

Money

required

Total of all discounts.

Money

required

Total of all taxes.

Money

required

Amount due on the invoice.

string | null

required

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

string | null

required

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

string | null

required

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

string

required

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

string

required

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

string

required

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

string | null

required

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

object

required

Cursor-based pagination metadata.

Show Pagination

boolean

required

Whether more results are available.

integer

required

Number of results in this page.

string

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

Example

{
  "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
    }
  }
}

{
  "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.

get_invoice

Fetch a single invoice by ID.

Result conventions

Learn how pagination, Money objects, and dual-channel output work across all tools.

Organizations

Transactions

Accounts

Cards

Statements

Contacts

Catalog items

Invoices

list_invoices — Filtered, paginated invoice list

Scope

Input

Output

Example

Notes

get_invoice

Result conventions

​Scope

​Input

​Output

​Example

​Notes

get_invoice

Result conventions

Scope

Input

Output

Example

Notes