list-credit-notes
Retrieve Xero credit notes by specifying a contact or viewing all entries. Supports pagination to fetch subsequent pages when more than 10 notes are returned.
Instructions
List credit notes in Xero. Ask the user if they want to see credit notes for a specific contact, or to see all credit notes before running. Ask the user if they want the next page of credit notes after running this tool if 10 credit notes are returned. If they want the next page, call this tool again with the next page number and the contact if one was provided in the previous call.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| contactId | No | ||
| page | Yes |
Implementation Reference
- Primary handler for the 'list-credit-notes' tool. Creates the tool using CreateXeroTool, defines input schema, and implements logic to fetch credit notes via listXeroCreditNotes and format them into text output.const ListCreditNotesTool = CreateXeroTool( "list-credit-notes", `List credit notes in Xero. Ask the user if they want to see credit notes for a specific contact, or to see all credit notes before running. Ask the user if they want the next page of credit notes after running this tool if 10 credit notes are returned. If they want the next page, call this tool again with the next page number and the contact if one was provided in the previous call.`, { page: z.number(), contactId: z.string().optional(), }, async ({ page, contactId }) => { const response = await listXeroCreditNotes(page, contactId); if (response.error !== null) { return { content: [ { type: "text" as const, text: `Error listing credit notes: ${response.error}`, }, ], }; } const creditNotes = response.result; return { content: [ { type: "text" as const, text: `Found ${creditNotes?.length || 0} credit notes:`, }, ...(creditNotes?.map((creditNote) => ({ type: "text" as const, text: [ `Credit Note ID: ${creditNote.creditNoteID}`, `Credit Note Number: ${creditNote.creditNoteNumber}`, creditNote.reference ? `Reference: ${creditNote.reference}` : null, `Type: ${creditNote.type || "Unknown"}`, `Status: ${creditNote.status || "Unknown"}`, creditNote.contact ? `Contact: ${creditNote.contact.name} (${creditNote.contact.contactID})` : null, creditNote.date ? `Date: ${creditNote.date}` : null, creditNote.lineAmountTypes ? `Line Amount Types: ${creditNote.lineAmountTypes}` : null, creditNote.subTotal ? `Sub Total: ${creditNote.subTotal}` : null, creditNote.totalTax ? `Total Tax: ${creditNote.totalTax}` : null, `Total: ${creditNote.total || 0}`, creditNote.currencyCode ? `Currency: ${creditNote.currencyCode}` : null, creditNote.currencyRate ? `Currency Rate: ${creditNote.currencyRate}` : null, creditNote.updatedDateUTC ? `Last Updated: ${creditNote.updatedDateUTC}` : null, ] .filter(Boolean) .join("\n"), })) || []), ], }; }, ); export default ListCreditNotesTool;
- Core handler function that fetches credit notes from Xero API using xeroClient.accountingApi.getCreditNotes, handles errors, and returns structured response.export async function listXeroCreditNotes( page: number = 1, contactId?: string, ): Promise<XeroClientResponse<CreditNote[]>> { try { const creditNotes = await getCreditNotes(contactId, page); return { result: creditNotes, isError: false, error: null, }; } catch (error) { return { result: null, isError: true, error: formatError(error), }; } }
- Helper function within the handler that performs the actual Xero API call to retrieve credit notes.async function getCreditNotes( contactId: string | undefined, page: number, ): Promise<CreditNote[]> { await xeroClient.authenticate(); const response = await xeroClient.accountingApi.getCreditNotes( xeroClient.tenantId, undefined, // ifModifiedSince contactId ? `Contact.ContactID=guid("${contactId}")` : undefined, // where "UpdatedDateUTC DESC", // order page, // page undefined, // unitdp 10, // pageSize getClientHeaders(), ); return response.body.creditNotes ?? []; }
- Zod schema defining tool inputs: required page number and optional contactId.page: z.number(), contactId: z.string().optional(), },
- src/tools/list/index.ts:32-58 (registration)Registers the ListCreditNotesTool as part of the ListTools array for tool collection.export const ListTools = [ ListAccountsTool, ListContactsTool, ListCreditNotesTool, ListInvoicesTool, ListItemsTool, ListManualJournalsTool, ListQuotesTool, ListTaxRatesTool, ListTrialBalanceTool, ListPaymentsTool, ListProfitAndLossTool, ListBankTransactionsTool, ListPayrollEmployeesTool, ListReportBalanceSheetTool, ListOrganisationDetailsTool, ListPayrollEmployeeLeaveTool, ListPayrollLeavePeriodsToolTool, ListPayrollEmployeeLeaveTypesTool, ListPayrollEmployeeLeaveBalancesTool, ListPayrollLeaveTypesTool, ListAgedReceivablesByContact, ListAgedPayablesByContact, ListPayrollTimesheetsTool, ListContactGroupsTool, ListTrackingCategoriesTool ];