preview_subscription_update
Preview subscription changes before applying them to verify proration, billing adjustments, and transaction outcomes without committing updates.
Instructions
This tool will preview an update for a subscription without applying those changes.
It's best practice to preview every time before updating the subscription to confirm the changes are as expected, especially when making updates to items, billing periods, and anything affecting proration.
The updateSummary object contains details of prorated credits and charges created, along with the overall result of the update.
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. | |
| customerId | No | Unique Paddle ID for this customer entity, prefixed with `ctm_`. | |
| addressId | No | Unique Paddle ID for this address entity, prefixed with `add_`. | |
| businessId | No | Paddle ID of the business that this subscription is for, prefixed with `biz_`. Include to change the business for a subscription. | |
| currencyCode | No | Supported three-letter ISO 4217 currency code. | |
| nextBilledAt | No | RFC 3339 datetime string. | |
| discount | No | Details of the discount applied to this subscription. Include to add a discount to a subscription. `null` to remove a discount. | |
| collectionMode | No | How payment is collected for transactions created for this subscription. `automatic` for checkout, `manual` for invoices. | |
| billingDetails | No | Details for invoicing. Required if `collectionMode` is `manual`. `null` if changing `collectionMode` to `automatic`. | |
| scheduledChange | No | Set to `null` to remove a scheduled change applied to a subscription. Pause the subscription, cancel the subscription, and resume the subscription to create scheduled changes instead. | |
| items | No | List of items on this subscription. Only recurring items may be added. Send the complete list of items that should be on this subscription, including existing items to retain. | |
| customData | No | Any structured custom key-value data needed outside of Paddle's standard fields. Occasionally used by third-parties. | |
| prorationBillingMode | No | How Paddle should handle proration calculation for changes made to a subscription or its items. Required when making changes that impact billing. For automatically-collected subscriptions, responses may take longer than usual if a proration billing mode that collects for payment immediately is used. | |
| 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:902-913 (handler)The handler function that implements the core logic of the 'preview_subscription_update' tool by calling paddle.subscriptions.previewUpdate.
export const previewSubscriptionUpdate = async ( paddle: Paddle, params: z.infer<typeof Parameters.previewSubscriptionUpdateParameters>, ) => { try { const { subscriptionId, ...updateData } = params; const subscription = await paddle.subscriptions.previewUpdate(subscriptionId, updateData); return subscription; } catch (error) { return error; } }; - src/tools.ts:602-612 (registration)Primary MCP tool registration entry, defining method name, description, input schema reference, and required permissions.
method: "preview_subscription_update", name: "Preview an update to a subscription", description: prompts.previewSubscriptionUpdatePrompt, parameters: params.previewSubscriptionUpdateParameters, actions: { subscriptions: { write: true, preview: true, }, }, }, - src/api.ts:82-82 (registration)API-level registration mapping the tool method constant to the handler function.
[TOOL_METHODS.PREVIEW_SUBSCRIPTION_UPDATE]: funcs.previewSubscriptionUpdate, - src/functions.ts:904-904 (schema)Type reference to the Zod schema for input parameters (defined in parameters.js).
params: z.infer<typeof Parameters.previewSubscriptionUpdateParameters>, - src/constants.ts:74-74 (helper)Constant defining the tool method string identifier.
PREVIEW_SUBSCRIPTION_UPDATE: "preview_subscription_update",