list_transactions
Retrieve and filter Paddle transaction records with pagination, sorting, and optional inclusion of related entities like customers, addresses, and adjustments.
Instructions
This tool will list transactions in Paddle.
Use the maximum perPage by default (30) to ensure comprehensive results. Filter transactions by billedAt, collectionMode, createdAt, customerId, id, invoiceNumber, origin, status, subscriptionId, and updatedAt 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. Amounts are in the smallest currency unit (e.g., cents).
Use the include parameter to include related entities in the response:
address: An object for the address entity related to this transaction. Only returned if an address is set against the transaction.
adjustments: An array of adjustment entities related to this transaction. Only returned if adjustments have been created against the transaction.
adjustments_totals: An object containing totals for all adjustments on a transaction. Only returned if adjustments have been created against the transaction.
available_payment_methods: An array of payment methods that are available to use for this transaction.
business: An object for the business entity related to this transaction. Only returned if a business is set against the transaction.
customer: An object for the customer entity related to this transaction. Only returned if a customer is set against the transaction.
discount: An object for the discount entity related to this transaction. Only returned if a discount is set against the transaction.
Transactions have a collectionMode that determines how Paddle tries to collect for payment:
automatic: Payment is collected automatically using a checkout initially, then using a payment method on file.
manual: Payment is collected manually. Customers are sent an invoice with payment terms and can make a payment offline or using a checkout. Requires billingDetails.
Transactions have a status that determines the current state of the transaction:
draft: Transaction is missing required fields. Typically the first stage of a checkout before customer details are captured.
ready: Transaction has all of the required fields to be marked as billed or completed.
billed: Transaction has been updated to billed. Billed transactions get an invoice number and are considered a legal record. They can't be changed. Typically used as part of an invoice workflow.
paid: Transaction is fully paid, but has not yet been processed internally.
completed: Transaction is fully paid and processed.
canceled: Transaction has been updated to canceled. If an invoice, it's no longer due.
past_due: Transaction is past due. Occurs for automatically-collected transactions when the related subscription is in dunning, and for manually-collected transactions when payment terms have elapsed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Return entities after the specified Paddle ID when working with paginated endpoints. | |
| billedAt | No | Return entities billed at this exact time. Pass an RFC 3339 datetime string. | |
| billedAtLT | No | Return entities billed before this time. Pass an RFC 3339 datetime string. | |
| billedAtLTE | No | Return entities billed at or before this time. Pass an RFC 3339 datetime string. | |
| billedAtGT | No | Return entities billed after this time. Pass an RFC 3339 datetime string. | |
| billedAtGTE | No | Return entities billed at or after this time. Pass an RFC 3339 datetime string. | |
| collectionMode | No | Return entities that match the specified collection mode. | |
| createdAt | No | Return entities created at this exact time. Pass an RFC 3339 datetime string. | |
| createdAtLT | No | Return entities created before this time. Pass an RFC 3339 datetime string. | |
| createdAtLTE | No | Return entities created at or before this time. Pass an RFC 3339 datetime string. | |
| createdAtGT | No | Return entities created after this time. Pass an RFC 3339 datetime string. | |
| createdAtGTE | No | Return entities created at or after this time. Pass an RFC 3339 datetime string. | |
| customerId | No | Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs. | |
| id | No | Return only the IDs specified. Use a comma-separated list to get multiple entities. | |
| include | No | Include related entities in the response. Use a comma-separated list to specify multiple entities. | |
| invoiceNumber | No | Return entities that match the invoice number. Use a comma-separated list to specify multiple invoice numbers. | |
| origin | No | Return entities related to the specified origin. Use a comma-separated list to specify multiple origins. | |
| orderBy | No | Order returned entities by the specified field and direction. | |
| status | No | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. | |
| subscriptionId | No | Return entities related to the specified subscription. Use a comma-separated list to specify multiple subscription IDs. Pass `null` to return entities that aren't related to any subscription. | |
| perPage | No | Set how many entities are returned per page. | |
| updatedAt | No | Return entities updated at this exact time. Pass an RFC 3339 datetime string. | |
| updatedAtLT | No | Return entities updated before this time. Pass an RFC 3339 datetime string. | |
| updatedAtLTE | No | Return entities updated at or before this time. Pass an RFC 3339 datetime string. | |
| updatedAtGT | No | Return entities updated after this time. Pass an RFC 3339 datetime string. | |
| updatedAtGTE | No | Return entities updated at or after this time. Pass an RFC 3339 datetime string. |
Implementation Reference
- src/functions.ts:121-134 (handler)The handler function that executes the list_transactions tool. It transforms input parameters using transformParams, calls paddle.transactions.list, fetches the first page with next(), computes pagination info, and returns paginated transactions or error.
export const listTransactions = async ( paddle: Paddle, params: z.infer<typeof Parameters.listTransactionsParameters>, ) => { try { const transformedParams = transformParams(params); const collection = paddle.transactions.list(transformedParams); const transactions = await collection.next(); const pagination = paginationData(collection); return { pagination, transactions }; } catch (error) { return error; } }; - src/tools.ts:373-383 (schema)Defines the tool schema for list_transactions, including method name, human-readable name, description prompt, Zod input parameters schema, and required actions (read/list on transactions).
method: "list_transactions", name: "List transactions", description: prompts.listTransactionsPrompt, parameters: params.listTransactionsParameters, actions: { transactions: { read: true, list: true, }, }, }, - src/api.ts:18-18 (registration)Registers the listTransactions handler function to the TOOL_METHODS.LIST_TRANSACTIONS key in the toolMap used by PaddleAPI to execute tools.
[TOOL_METHODS.LIST_TRANSACTIONS]: funcs.listTransactions, - src/functions.ts:16-37 (helper)Helper utility to transform query parameters from underscore notation (e.g., 'created_at_lt') to Paddle API bracket notation (e.g., 'created_at[LT]'), specifically used in listTransactions.
// Example: created_at_lt becomes created_at[LT], updated_at_gte becomes updated_at[GTE] // Other parameters like customer_id, collection_mode are left unchanged const transformParams = (params: Record<string, unknown>) => { const operators = ["lt", "lte", "gt", "gte"]; return Object.entries(params).reduce( (acc, [key, value]) => { const parts = key.split("_"); const lastPart = parts[parts.length - 1]; if (parts.length >= 2 && operators.includes(lastPart)) { const operator = parts.pop()!; const base = parts.join("_"); acc[`${base}[${operator.toUpperCase()}]`] = value; } else { acc[key] = value; } return acc; }, {} as Record<string, unknown>, ); }; - src/functions.ts:10-13 (helper)Helper to extract pagination metadata (hasMore, estimatedTotal) from Paddle paginated collection, used in listTransactions response.
const paginationData = (collection: PaginatedCollection) => ({ hasMore: collection.hasMore, estimatedTotal: collection.estimatedTotal, });