get_transaction
Retrieve a transaction from Paddle Billing by its ID, with options to include related entities like customer, address, adjustments, and business details.
Instructions
This tool will retrieve a transaction from Paddle by its ID.
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 |
|---|---|---|---|
| transactionId | Yes | Paddle ID of the transaction. | |
| include | No | Include related entities in the response. Use a comma-separated list to specify multiple entities. |
Implementation Reference
- src/functions.ts:169-177 (handler)The core handler function that executes the 'get_transaction' tool logic. It takes a transactionId and optional query parameters, calls the Paddle SDK's transactions.get method, and returns the transaction data or error.
export const getTransaction = async (paddle: Paddle, params: z.infer<typeof Parameters.getTransactionParameters>) => { try { const { transactionId, ...queryParams } = params; const hasQueryParams = Object.keys(queryParams).length > 0; const transaction = await paddle.transactions.get(transactionId, hasQueryParams ? queryParams : undefined); return transaction; } catch (error) { return error; } - src/tools.ts:396-407 (registration)Tool registration/definition in the tools array, specifying the method name, description, input schema (parameters), and required actions/permissions.
{ method: "get_transaction", name: "Get a transaction", description: prompts.getTransactionPrompt, parameters: params.getTransactionParameters, actions: { transactions: { read: true, get: true, }, }, }, - src/tools.ts:400-400 (schema)Reference to the Zod input schema for validating parameters of the get_transaction tool.
parameters: params.getTransactionParameters, - src/api.ts:22-22 (registration)Maps the TOOL_METHODS.GET_TRANSACTION constant to the getTransaction handler function in the toolMap object used by PaddleAPI.
[TOOL_METHODS.GET_TRANSACTION]: funcs.getTransaction, - src/constants.ts:14-14 (helper)Constant definition for the tool method name used across the codebase.
GET_TRANSACTION: "get_transaction",