list_customers
Retrieve and manage customer data from your Paddle account by filtering, searching, and sorting results. Use pagination to access comprehensive lists of active or archived customers by email, ID, or status.
Instructions
This tool will list customers in your Paddle account.
Use the maximum perPage by default (200) to ensure comprehensive results. Filter customers by email, ID, and status as needed. Use the search parameter to find customers by ID, name, or email address. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort results using orderBy parameter. Customers can have either 'active' or 'archived' status.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Return entities after the specified Paddle ID when working with paginated endpoints. | |
| No | Return entities that exactly match the specified email address. | ||
| id | No | Return only the IDs specified. | |
| orderBy | No | Order returned entities by the specified field and direction. | |
| perPage | No | Set how many entities are returned per page. Default: 50; Maximum: 200. | |
| search | No | Return entities that match a search query. Searches id, name, and email fields. | |
| status | No | Return entities that match the specified status. |
Implementation Reference
- src/functions.ts:260-269 (handler)The core handler function for the 'list_customers' tool. It lists customers using the Paddle SDK's customers.list method with the provided parameters, fetches the first page of results, computes pagination data, and returns the customers list along with pagination info. Errors are caught and returned directly.export const listCustomers = async (paddle: Paddle, params: z.infer<typeof Parameters.listCustomersParameters>) => { try { const collection = paddle.customers.list(params); const customers = await collection.next(); const pagination = paginationData(collection); return { pagination, customers }; } catch (error) { return error; } };
- src/tools.ts:229-239 (registration)Registers the 'list_customers' tool in the tools array, specifying the method name, human-readable name, description prompt, Zod parameters schema, and required permission actions for customers (read/list).method: "list_customers", name: "List customers", description: prompts.listCustomersPrompt, parameters: params.listCustomersParameters, actions: { customers: { read: true, list: true, }, }, },
- src/api.ts:29-29 (registration)Maps the LIST_CUSTOMERS tool method constant to its handler function (funcs.listCustomers) in the toolMap used by the PaddleAPI to dispatch tool calls.[TOOL_METHODS.LIST_CUSTOMERS]: funcs.listCustomers,
- src/functions.ts:10-13 (helper)Helper function used by listCustomers (and other list tools) to extract pagination metadata (hasMore, estimatedTotal) from the PaginatedCollection returned by Paddle SDK.const paginationData = (collection: PaginatedCollection) => ({ hasMore: collection.hasMore, estimatedTotal: collection.estimatedTotal, });
- src/constants.ts:21-21 (registration)Defines the LIST_CUSTOMERS constant as 'list_customers' string, used in tool registrations and mappings.LIST_CUSTOMERS: "list_customers",