preview_transaction_create
Preview transaction totals and details without creating an actual transaction. Calculate tax, apply discounts, and see itemized breakdowns before finalizing payments.
Instructions
This tool will preview a transaction without creating a transaction entity.
Consider using the preview_prices tool for simpler pricing calculations where payment is often taken through checkout.
Providing location information when previewing a transaction allows Paddle to calculate tax or automatically localize prices. Provide one of the following:
customer_ip_address: Paddle fetches location using the IP address to calculate totals.
address: Paddle uses the country and ZIP code (where supplied) to calculate totals.
customerId, addressId, businessId: Paddle uses existing customer data to calculate totals. Typically used for logged-in customers.
Exclude items from the total calculation using the includeInTotals boolean.
By default, recurring items with trials are considered to have a zero charge when previewing. Set ignoreTrials to true to ignore trial periods against prices for transaction preview calculations.
Transaction previews don't create transactions, so no id is returned.
If successful, the response includes the data sent with a details object that includes totals for the supplied prices.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| customerId | No | Paddle ID of the customer that this transaction preview is for, prefixed with `ctm_`. | |
| currencyCode | No | Supported three-letter ISO 4217 currency code. | |
| discountId | No | Paddle ID of the discount applied to this transaction preview, prefixed with `dsc_`. | |
| ignoreTrials | No | Whether trials should be ignored for transaction preview calculations. By default, recurring items with trials are considered to have a zero charge when previewing. Set to `true` to disable this. | |
| items | Yes | List of items to preview charging for. Preview charging for items that have been added to the catalog by passing the Paddle ID of an existing price entity, or preview charging for non-catalog items by passing a price object. Non-catalog items can be for existing products, or pass a product object as part of the price to preview charging for a non-catalog product. | |
| address | Yes | Represents an address entity when previewing addresses. | |
| customerIpAddress | Yes | IP address for this transaction preview. | |
| addressId | Yes | Paddle ID of the address that this transaction preview is for, prefixed with `add_`. | |
| businessId | No | Paddle ID of the business that this transaction preview is for, prefixed with `biz_`. |
Implementation Reference
- src/functions.ts:157-167 (handler)The primary handler function that executes the tool logic by calling the Paddle SDK's transactions.preview method with the provided parameters.
export const previewTransactionCreate = async ( paddle: Paddle, params: z.infer<typeof Parameters.previewTransactionCreateParameters>, ) => { try { const transaction = await paddle.transactions.preview(params); return transaction; } catch (error) { return error; } }; - src/tools.ts:432-443 (registration)Registers the tool in the main tools array, specifying the method name, human-readable name, description prompt, input schema reference, and required permissions/actions.
{ method: "preview_transaction_create", name: "Preview a transaction", description: prompts.previewTransactionCreatePrompt, parameters: params.previewTransactionCreateParameters, actions: { transactions: { write: true, preview: true, }, }, }, - src/api.ts:21-21 (registration)Maps the tool method constant to the corresponding handler function in the PaddleAPI toolMap for execution routing.
[TOOL_METHODS.PREVIEW_TRANSACTION_CREATE]: funcs.previewTransactionCreate, - src/constants.ts:13-13 (registration)Defines the string constant for the tool method name used across registrations and mappings.
PREVIEW_TRANSACTION_CREATE: "preview_transaction_create", - src/prompts.ts:332-350 (helper)Provides the descriptive prompt text for the tool, used in the registration to guide LLM usage.
export const previewTransactionCreatePrompt = ` This tool will preview a transaction without creating a transaction entity. Consider using the preview_prices tool for simpler pricing calculations where payment is often taken through checkout. Providing location information when previewing a transaction allows Paddle to calculate tax or automatically localize prices. Provide one of the following: - customer_ip_address: Paddle fetches location using the IP address to calculate totals. - address: Paddle uses the country and ZIP code (where supplied) to calculate totals. - customerId, addressId, businessId: Paddle uses existing customer data to calculate totals. Typically used for logged-in customers. Exclude items from the total calculation using the includeInTotals boolean. By default, recurring items with trials are considered to have a zero charge when previewing. Set ignoreTrials to true to ignore trial periods against prices for transaction preview calculations. Transaction previews don't create transactions, so no id is returned. If successful, the response includes the data sent with a details object that includes totals for the supplied prices. `;