get_invoice — Retrieve a single invoice

The get_invoice tool returns a single invoice by invoiceId within an organization, including line items, taxes, discounts, totals, and links. intent, organizationId, and invoiceId are required, 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 that owns the invoice. Must be one of the organizations the token can access.

string

required

The unique invoice identifier to retrieve.

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

The requested invoice.

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.

Example

{
  "jsonrpc": "2.0",
  "id": 15,
  "method": "tools/call",
  "params": {
    "name": "get_invoice",
    "arguments": {
      "intent": "User asked for the total and payment link for invoice INV-0042.",
      "organizationId": "org_1",
      "invoiceId": "inv_1"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 15,
  "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>"
      }
    }
  }
}

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.
If the invoice does not exist or is not accessible with the provided token, the tool returns an MCP error: Invoice not found or not accessible.

list_invoices

Search and list invoices.

get_contact

Look up the contact an invoice is billed to.

Organizations

Transactions

Accounts

Cards

Statements

Contacts

Catalog items

Invoices

get_invoice — Retrieve a single invoice

Scope

Input

Output

Example

Notes

list_invoices

get_contact

​Scope

​Input

​Output

​Example

​Notes

list_invoices

get_contact

Scope

Input

Output

Example

Notes