list_addresses
Read-only
Retrieve and manage customer addresses in Paddle with filtering, pagination, and sorting options for efficient address management.
Instructions
This tool will list addresses for a customer in Paddle.
Use the maximum perPage by default (200) to ensure comprehensive results. Filter addresses by id, search (fuzzy search on the address's street, city, state, postalCode, or country), 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 |
|---|---|---|---|
| customerId | Yes | Paddle ID of the customer. | |
| after | No | Return entities after the specified Paddle ID when working with paginated endpoints. | |
| 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 street, city, state, postal code, or country. | |
| status | No | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. |
Implementation Reference
- src/functions.ts:300-310 (handler)The main handler function that executes the list_addresses tool. It takes a customerId and optional query parameters, lists addresses using the Paddle SDK, fetches the first page, adds pagination info, and returns the result or error.
export const listAddresses = async (paddle: Paddle, params: z.infer<typeof Parameters.listAddressesParameters>) => { try { const { customerId, ...queryParams } = params; const collection = paddle.addresses.list(customerId, queryParams); const addresses = await collection.next(); const pagination = paginationData(collection); return { pagination, addresses }; } catch (error) { return error; } }; - src/tools.ts:277-287 (registration)MCP tool registration block defining the list_addresses tool, including method name, human name, description prompt reference, Zod parameters schema reference, and required actions (read/list on addresses).
method: "list_addresses", name: "List addresses for a customer", description: prompts.listAddressesPrompt, parameters: params.listAddressesParameters, actions: { addresses: { read: true, list: true, }, }, }, - src/api.ts:33-33 (registration)Maps the LIST_ADDRESSES tool method constant to the listAddresses handler function in the PaddleAPI toolMap for execution.
[TOOL_METHODS.LIST_ADDRESSES]: funcs.listAddresses, - src/functions.ts:10-13 (helper)Helper function to extract pagination metadata (hasMore, estimatedTotal) from Paddle SDK collection objects, used in the listAddresses handler.
const paginationData = (collection: PaginatedCollection) => ({ hasMore: collection.hasMore, estimatedTotal: collection.estimatedTotal, }); - src/constants.ts:25-25 (helper)Constant defining the string identifier for the list_addresses tool method, used in registrations and mappings.
LIST_ADDRESSES: "list_addresses",