list_customers
Retrieve customers with optional filtering by status, search term, and pagination. Optionally include related data such as subscriptions, invoices, or payment methods.
Instructions
List customers with optional query parameters for filtering and pagination. GET /customers. See https://apiguide.rebillia.com/ for the Public API.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| pageNo | No | Page number (default: 1) | |
| itemPerPage | No | Items per page (default: 25, max 250) | |
| query | No | Search term: matches firstName, lastName, email, and related company name/support pin | |
| status | No | Filter by customer status: active, disabled, or archived | |
| sortBy | No | Sort direction: ASC or DESC (default: ASC for customers) | |
| orderBy | No | Column to sort by (e.g. firstName, lastName, email, createdAt). Default: firstName | |
| include | No | Comma-separated includes: addressbook, paymentmethod, lastInvoice, subscriptions, unpaidInvoices, externalCustomers | |
| filterId | No | Optional saved filter ID to apply predefined filters |
Implementation Reference
- Handler function for list_customers tool. Extracts arguments (pageNo, itemPerPage, query, status, sortBy, orderBy, include, filterId) from args, maps them to ListCustomersParams, then delegates to the customer service's listCustomers function via handleToolCall.
async function handler(client: Client, args: Record<string, unknown> | undefined) { const a = (args ?? {}) as Record<string, unknown>; const params: customerService.ListCustomersParams = { pageNo: a.pageNo != null ? Number(a.pageNo) : undefined, itemPerPage: a.itemPerPage != null ? Number(a.itemPerPage) : undefined, query: typeof a.query === "string" ? a.query : undefined, status: typeof a.status === "string" ? a.status : undefined, sortBy: typeof a.sortBy === "string" ? a.sortBy : undefined, orderBy: typeof a.orderBy === "string" ? a.orderBy : undefined, include: typeof a.include === "string" ? a.include : undefined, filterId: a.filterId != null ? Number(a.filterId) : undefined, }; return handleToolCall(() => customerService.listCustomers(client, params)); } export const listCustomersTool: Tool = { definition, handler, }; - MCP tool definition and input schema for list_customers. Defines the tool name, description, and inputSchema with optional parameters: pageNo, itemPerPage, query, status, sortBy, orderBy, include, filterId.
const definition = { name: "list_customers", description: "List customers with optional query parameters for filtering and pagination. GET /customers. See https://apiguide.rebillia.com/ for the Public API.", inputSchema: { type: "object" as const, properties: { pageNo: { type: "number", description: "Page number (default: 1)" }, itemPerPage: { type: "number", description: "Items per page (default: 25, max 250)" }, query: { type: "string", description: "Search term: matches firstName, lastName, email, and related company name/support pin", }, status: { type: "string", description: "Filter by customer status: active, disabled, or archived", }, sortBy: { type: "string", description: "Sort direction: ASC or DESC (default: ASC for customers)" }, orderBy: { type: "string", description: "Column to sort by (e.g. firstName, lastName, email, createdAt). Default: firstName", }, include: { type: "string", description: "Comma-separated includes: addressbook, paymentmethod, lastInvoice, subscriptions, unpaidInvoices, externalCustomers", }, filterId: { type: "number", description: "Optional saved filter ID to apply predefined filters" }, }, }, }; - TypeScript interface for ListCustomersParams defining the typed parameters used by the service layer.
export interface ListCustomersParams { pageNo?: number; itemPerPage?: number; query?: string; status?: string; sortBy?: string; orderBy?: string; include?: string; filterId?: number; } - src/tools/customers/index.ts:31-56 (registration)Registration of list_customers tool: listCustomersTool is included in the registerCustomerTools() array that aggregates all customer tools for the main registry.
export function registerCustomerTools(): Tool[] { return [ listCustomersTool, getCustomerTool, createCustomerTool, updateCustomerTool, deleteCustomerTool, getCustomerInvoicesTool, getCustomerUnpaidInvoicesTool, getCustomerSubscriptionsTool, getCustomerLogsTool, listCustomerAddressesTool, getCustomerAddressTool, createCustomerAddressTool, updateCustomerAddressTool, deleteCustomerAddressTool, listCustomerPaymentMethodsTool, getCustomerPaymentMethodTool, createCustomerPaymentMethodTool, updateCustomerPaymentMethodTool, deleteCustomerPaymentMethodTool, listCustomerChargesCreditsTool, createCustomerChargeCreditTool, deleteCustomerChargeCreditTool, ]; } - Service-level function that builds query parameters and makes the GET /customers API call via the HTTP client, returning a PaginatedResponse of Customer objects.
export async function listCustomers( client: Client, params: ListCustomersParams ): Promise<PaginatedResponse<Customer>> { const search = new URLSearchParams(); if (params.pageNo != null) search.append("pageNo", String(params.pageNo)); if (params.itemPerPage != null) search.append("itemPerPage", String(params.itemPerPage)); if (params.query) search.append("query", params.query); if (params.status) search.append("status", params.status); if (params.sortBy) search.append("sortBy", params.sortBy); if (params.orderBy) search.append("orderBy", params.orderBy); if (params.include) search.append("include", params.include); if (params.filterId != null) search.append("filterId", String(params.filterId)); return client.get<PaginatedResponse<Customer>>(`/customers${queryString(search)}`); }