list-payments
Retrieve and filter payment records from Xero accounting software by invoice number, ID, payment ID, or reference to track financial transactions and payment history.
Instructions
List payments in Xero. This tool shows all payments made against invoices, including payment date, amount, and payment method. You can filter payments by invoice number, invoice ID, payment ID, or invoice reference. Ask the user if they want to see payments for a specific invoice, contact, payment or reference before running. If many payments are returned, ask the user if they want to see the next page.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| invoiceNumber | No | ||
| invoiceId | No | ||
| paymentId | No | ||
| reference | No |
Implementation Reference
- The main handler function for the 'list-payments' tool. It calls the listXeroPayments helper, handles errors, and formats the payments into readable text blocks.
async ({ page, invoiceNumber, invoiceId, paymentId, reference }) => { const response = await listXeroPayments(page, { invoiceNumber, invoiceId, paymentId, reference, }); if (response.error !== null) { return { content: [ { type: "text" as const, text: `Error listing payments: ${response.error}`, }, ], }; } const payments = response.result; return { content: [ { type: "text" as const, text: `Found ${payments?.length || 0} payments:`, }, ...(payments?.map((payment) => ({ type: "text" as const, text: paymentFormatter(payment), })) || []), ], }; }, - Zod schema defining the input parameters for the list-payments tool: page, invoiceNumber, invoiceId, paymentId, reference.
page: z.number().default(1), invoiceNumber: z.string().optional(), invoiceId: z.string().optional(), paymentId: z.string().optional(), reference: z.string().optional(), }, - src/tools/tool-factory.ts:20-22 (registration)Registration of the list-payments tool (as part of ListTools) by calling server.tool with its name, description, schema, and handler.
ListTools.map((tool) => tool()).forEach((tool) => server.tool(tool.name, tool.description, tool.schema, tool.handler), ); - Core helper function that queries the Xero API for payments based on filters and returns structured response or error.
export async function listXeroPayments( page: number = 1, { invoiceNumber, invoiceId, paymentId, reference, }: { invoiceNumber?: string; invoiceId?: string; paymentId?: string; reference?: string; }, ): Promise<XeroClientResponse<Payment[]>> { try { const payments = await getPayments(page, { invoiceNumber, invoiceId, paymentId, reference, }); return { result: payments, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } } - Helper function to format a single payment object into a human-readable string.
function paymentFormatter(payment: Payment): string { return [ `Payment ID: ${payment.paymentID || "Unknown"}`, `Date: ${payment.date || "Unknown date"}`, `Amount: ${payment.amount || 0}`, payment.reference ? `Reference: ${payment.reference}` : null, payment.status ? `Status: ${payment.status}` : null, payment.paymentType ? `Payment Type: ${payment.paymentType}` : null, payment.updatedDateUTC ? `Last Updated: ${payment.updatedDateUTC}` : null, payment.account?.name ? `Account: ${payment.account.name} (${payment.account.accountID || "Unknown ID"})` : null, payment.invoice ? [ `Invoice:`, ` Invoice Number: ${payment.invoice.invoiceNumber || "Unknown"}`, ` Invoice ID: ${payment.invoice.invoiceID || "Unknown"}`, payment.invoice.contact ? ` Contact: ${payment.invoice.contact.name || "Unknown"} (${payment.invoice.contact.contactID || "Unknown ID"})` : null, payment.invoice.type ? ` Type: ${payment.invoice.type}` : null, payment.invoice.total !== undefined ? ` Total: ${payment.invoice.total}` : null, payment.invoice.amountDue !== undefined ? ` Amount Due: ${payment.invoice.amountDue}` : null, ] .filter(Boolean) .join("\n") : null, ] .filter(Boolean) .join("\n"); }