Paddle MCP Server

Official

Overview Schema Source Related Servers Discussions Admin

list_transactions

Read-only

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

TableJSON Schema

Name	Required	Description
`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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed36 schema fields changedv1.0.0Jan 2, 2026

changedInput schema / properties / billedAt / description

Previous value: -"Return entities billed at a specific time. Pass an RFC 3339 datetime string."New value: +"Return entities billed at this exact time. Pass an RFC 3339 datetime string."

addedInput schema / properties / billedAtGT

Added value: +{
+  "description": "Return entities billed after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / billedAtGTE

Added value: +{
+  "description": "Return entities billed at or after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / billedAtLT

Added value: +{
+  "description": "Return entities billed before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / billedAtLTE

Added value: +{
+  "description": "Return entities billed at or before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

removedInput schema / properties / billedAt_gt

Removed value: -{
-  "description": "Return entities billed after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / billedAt_gte

Removed value: -{
-  "description": "Return entities billed at or after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / billedAt_lt

Removed value: -{
-  "description": "Return entities billed before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / billedAt_lte

Removed value: -{
-  "description": "Return entities billed at or before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

changedInput schema / properties / createdAt / description

Previous value: -"Return entities created at a specific time. Pass an RFC 3339 datetime string."New value: +"Return entities created at this exact time. Pass an RFC 3339 datetime string."

addedInput schema / properties / createdAtGT

Added value: +{
+  "description": "Return entities created after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / createdAtGTE

Added value: +{
+  "description": "Return entities created at or after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / createdAtLT

Added value: +{
+  "description": "Return entities created before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / createdAtLTE

Added value: +{
+  "description": "Return entities created at or before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

removedInput schema / properties / createdAt_gt

Removed value: -{
-  "description": "Return entities created after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / createdAt_gte

Removed value: -{
-  "description": "Return entities created at or after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / createdAt_lt

Removed value: -{
-  "description": "Return entities created before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / createdAt_lte

Removed value: -{
-  "description": "Return entities created at or before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

changedInput schema / properties / customerId / description

Previous value: -"Return entities related to the specified customer."New value: +"Return entities related to the specified customer. Use a comma-separated list to specify multiple customer IDs."

changedInput schema / properties / id / description

Previous value: -"Return only the IDs specified."New value: +"Return only the IDs specified. Use a comma-separated list to get multiple entities."

changedInput schema / properties / include / description

Previous value: -"Include related entities in the response."New value: +"Include related entities in the response. Use a comma-separated list to specify multiple entities."

changedInput schema / properties / include / items / enum

Previous value: -[
-  "address",
-  "adjustment",
-  "adjustments_totals",
-  "business",
-  "customer",
-  "discount"
-]New value: +[
+  "address",
+  "adjustments",
+  "adjustments_totals",
+  "available_payment_methods",
+  "business",
+  "customer",
+  "discount"
+]

changedInput schema / properties / invoiceNumber / description

Previous value: -"Return entities that match the invoice number."New value: +"Return entities that match the invoice number. Use a comma-separated list to specify multiple invoice numbers."

changedInput schema / properties / orderBy / description

Previous value: -"Order returned entities by field and direction."New value: +"Order returned entities by the specified field and direction."

changedInput schema / properties / origin / description

Previous value: -"Return entities related to the specified origin."New value: +"Return entities related to the specified origin. Use a comma-separated list to specify multiple origins."

changedInput schema / properties / status / description

Previous value: -"Return entities that match the specified status."New value: +"Return entities that match the specified status. Use a comma-separated list to specify multiple status values."

changedInput schema / properties / subscriptionId / description

Previous value: -"Return entities related to the specified subscription. Pass null to return entities not related to any subscription."New value: +"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."

changedInput schema / properties / updatedAt / description

Previous value: -"Return entities updated at a specific time. Pass an RFC 3339 datetime string."New value: +"Return entities updated at this exact time. Pass an RFC 3339 datetime string."

addedInput schema / properties / updatedAtGT

Added value: +{
+  "description": "Return entities updated after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / updatedAtGTE

Added value: +{
+  "description": "Return entities updated at or after this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / updatedAtLT

Added value: +{
+  "description": "Return entities updated before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

addedInput schema / properties / updatedAtLTE

Added value: +{
+  "description": "Return entities updated at or before this time. Pass an RFC 3339 datetime string.",
+  "type": "string"
+}

removedInput schema / properties / updatedAt_gt

Removed value: -{
-  "description": "Return entities updated after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / updatedAt_gte

Removed value: -{
-  "description": "Return entities updated at or after a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / updatedAt_lt

Removed value: -{
-  "description": "Return entities updated before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

removedInput schema / properties / updatedAt_lte

Removed value: -{
-  "description": "Return entities updated at or before a specific time. Pass an RFC 3339 datetime string.",
-  "type": "string"
-}

First observedApr 1, 2025

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral context beyond the readOnlyHint annotation. It explains pagination mechanics ('use the 'after' parameter with the last ID'), data format details ('amounts are in the smallest currency unit'), collectionMode behaviors (automatic vs manual), and status definitions with workflow implications. This provides rich operational context that annotations alone don't cover.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is comprehensive but verbose at 22 sentences. While information is valuable, it could be more front-loaded with critical details. The lengthy explanations of collectionMode and status could be condensed, though they do earn their place by providing important behavioral context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (26 parameters, no output schema), the description provides excellent completeness. It covers pagination, filtering, sorting, data formats, include options, and detailed explanations of collectionMode and status - essentially everything needed to use the tool effectively despite the lack of output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the baseline is 3. The description adds meaningful context about parameter usage: it explains the 'include' parameter's purpose and what each option returns, clarifies that amounts use smallest currency units, and provides guidance on default pagination behavior. However, it doesn't fully explain all 26 parameters' interactions or edge cases.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states 'list transactions in Paddle' - a specific verb ('list') and resource ('transactions') with clear scope ('in Paddle'). It distinguishes from sibling tools like 'get_transaction' (singular retrieval) and 'create_transaction' (creation operation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context with pagination guidance ('use the maximum perPage by default'), filtering capabilities, and include parameter usage. However, it doesn't explicitly state when to use this tool versus alternatives like 'get_transaction' for single transactions or other list_* tools for different resources.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

list_transactions

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools