preview_subscription_charge
Preview one-time charges for a subscription to calculate expected transactions before applying changes, without billing the customer.
Instructions
This tool will preview creating a one-time charge for a subscription without billing that charge, typically used for previewing calculations before making changes to a subscription.
One-time charges are non-recurring items. These are price entities where the billingCycle is null.
If successful, the response includes immediateTransaction, nextTransaction, and recurringTransactionDetails to see expected transactions for the changes.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| subscriptionId | Yes | Paddle ID of the subscription. | |
| effectiveFrom | Yes | When one-time charges should be billed. | |
| items | Yes | List of one-time charges to bill for. Only prices where the `billingCycle` is `null` may be added. Charge for items that have been added to the catalog by passing the Paddle ID of an existing price entity, or charge 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 charge for a non-catalog product. | |
| onPaymentFailure | No | How Paddle should handle changes made to a subscription or its items if the payment fails during update. If omitted, defaults to `prevent_change`. |
Implementation Reference
- src/functions.ts:928-939 (handler)The primary handler function implementing the tool logic. It previews a one-time charge on a subscription by calling the Paddle SDK's previewOneTimeCharge method.export const previewSubscriptionCharge = async ( paddle: Paddle, params: z.infer<typeof Parameters.previewSubscriptionChargeParameters>, ) => { try { const { subscriptionId, ...updateData } = params; const subscription = await paddle.subscriptions.previewOneTimeCharge(subscriptionId, updateData); return subscription; } catch (error) { return error; } };
- src/tools.ts:625-636 (registration)Tool registration in the tools array, defining method name, human-readable name, description prompt, input parameters schema, and required permissions/actions.{ method: "preview_subscription_charge", name: "Preview a one-time charge for a subscription", description: prompts.previewSubscriptionChargePrompt, parameters: params.previewSubscriptionChargeParameters, actions: { subscriptions: { write: true, preview: true, }, }, },
- src/api.ts:83-85 (registration)Mapping of the tool method constant to its handler function in the PaddleAPI toolMap.[TOOL_METHODS.CREATE_SUBSCRIPTION_CHARGE]: funcs.createSubscriptionCharge, [TOOL_METHODS.PREVIEW_SUBSCRIPTION_CHARGE]: funcs.previewSubscriptionCharge, [TOOL_METHODS.LIST_REPORTS]: funcs.listReports,
- src/constants.ts:74-77 (registration)Constant definition for the tool method string used across registrations and mappings.PREVIEW_SUBSCRIPTION_UPDATE: "preview_subscription_update", CREATE_SUBSCRIPTION_CHARGE: "create_subscription_charge", PREVIEW_SUBSCRIPTION_CHARGE: "preview_subscription_charge", LIST_REPORTS: "list_reports",