list_customers
Retrieve and filter customer data from Paddle Billing with options for pagination, search by email or name, and sorting by ID.
Instructions
This tool will list customers in Paddle.
Use the maximum perPage by default (200) to ensure comprehensive results. Filter customers by email, id, search (fuzzy search on the customer's name), and status as needed. Results are paginated - use the 'after' parameter with the last ID from previous results to get the next page. Sort and order results using the orderBy parameter.
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. Use a comma-separated list to specify multiple email addresses. Recommended for precise matching of email addresses. | ||
| id | No | Return only the IDs specified. Use a comma-separated list to get multiple entities. | |
| orderBy | No | Order returned entities by the specified field and direction. | |
| perPage | No | Set how many entities are returned per page. Returns the maximum number of results if a number greater than the maximum is requested. | |
| search | No | Return entities that match a search query. Pass an exact match for the customer's name. Use the `email` query parameter for precise matching of email addresses. | |
| status | No | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. |
Implementation Reference
- src/functions.ts:260-269 (handler)The handler function that implements the core logic for listing customers using the Paddle SDK, handling pagination and errors.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:228-239 (schema)Defines the tool schema for 'list_customers', including method, name, description, Zod parameters schema, and required permissions/actions.{ method: "list_customers", name: "List customers", description: prompts.listCustomersPrompt, parameters: params.listCustomersParameters, actions: { customers: { read: true, list: true, }, }, },
- src/api.ts:29-29 (registration)Registers the 'list_customers' tool by mapping the constant TOOL_METHODS.LIST_CUSTOMERS to the handler function in the toolMap used by PaddleAPI.[TOOL_METHODS.LIST_CUSTOMERS]: funcs.listCustomers,
- src/functions.ts:10-13 (helper)Helper function used by the handler to extract pagination metadata from the Paddle collection.const paginationData = (collection: PaginatedCollection) => ({ hasMore: collection.hasMore, estimatedTotal: collection.estimatedTotal, });
- src/constants.ts:21-21 (registration)Constant defining the string identifier for the 'list_customers' tool method, used in registration and schema.LIST_CUSTOMERS: "list_customers",