create_subscription_charge
Add one-time charges to a Paddle subscription for non-recurring items, billing immediately or on the next renewal period.
Instructions
This tool will create a one-time charge for a subscription in Paddle. Use to bill non-recurring items to a subscription. Non-recurring items are price entities where the billingCycle is null.
Don't use this tool without checking with the user first. Avoid using before gaining explicit approval.
When selecting effectiveFrom, choose the one that best describes when the one-time charges should be billed:
next_billing_period: Bill for one-time charges on the next billing period. Paddle adds the charges to the transaction created when the subscription next renews.
immediately: Bill for one-time charges now. Paddle creates a transaction for them right away. For automatically-collected subscriptions, responses may take longer than usual while a payment attempt is processed.
When selecting onPaymentFailure, choose the one that best describes how Paddle should handle subscription updates when payment fails during one-time charges:
prevent_change: Prevent the change to the subscription from applying.
apply_change: Apply the change and update the subscription.
Once created, to get details of a one-time charge:
When created with effectiveFrom as next_billing_period, get the subscription the charge was billed to and use the include query parameter with the nextTransaction value.
When created with effectiveFrom as immediately, list transactions and use the subscriptionId query parameter with the subscription ID of the subscription the charge was billed to.
When an update results in an immediate charge, responses may take longer than usual while a payment attempt is processed.
Ensure you have all the information needed before making the call. Don't fabricate, imagine, or infer details and parameter values unless explicitly asked to. If anything is ambiguous, unknown, or unclear, ask the user for clarification or details before you proceed.
If successful, the response includes a copy of the updated subscription entity. However, one-time charges aren't held against the subscription entity, so the charges billed aren't returned in the response.
Input 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:915-926 (handler)The handler function that implements the core logic of the 'create_subscription_charge' tool. It takes a Paddle instance and validated parameters, destructures the subscriptionId, calls paddle.subscriptions.createOneTimeCharge with the ID and remaining data, and returns the subscription or error.
export const createSubscriptionCharge = async ( paddle: Paddle, params: z.infer<typeof Parameters.createSubscriptionChargeParameters>, ) => { try { const { subscriptionId, ...updateData } = params; const subscription = await paddle.subscriptions.createOneTimeCharge(subscriptionId, updateData); return subscription; } catch (error) { return error; } }; - src/tools.ts:614-624 (registration)Primary registration of the tool in the tools array exported from tools.ts. Defines the method name, human-readable name, description prompt, input schema reference, and required permissions/actions.
method: "create_subscription_charge", name: "Create a one-time charge for a subscription", description: prompts.createSubscriptionChargePrompt, parameters: params.createSubscriptionChargeParameters, actions: { subscriptions: { write: true, create: true, }, }, }, - src/api.ts:70-93 (registration)Maps the CREATE_SUBSCRIPTION_CHARGE constant to the createSubscriptionCharge handler function in the toolMap object used by PaddleAPI to execute tools.
[TOOL_METHODS.LIST_DISCOUNT_GROUPS]: funcs.listDiscountGroups, [TOOL_METHODS.CREATE_DISCOUNT_GROUP]: funcs.createDiscountGroup, [TOOL_METHODS.GET_DISCOUNT_GROUP]: funcs.getDiscountGroup, [TOOL_METHODS.UPDATE_DISCOUNT_GROUP]: funcs.updateDiscountGroup, [TOOL_METHODS.ARCHIVE_DISCOUNT_GROUP]: funcs.archiveDiscountGroup, [TOOL_METHODS.GET_SUBSCRIPTION]: funcs.getSubscription, [TOOL_METHODS.UPDATE_SUBSCRIPTION]: funcs.updateSubscription, [TOOL_METHODS.LIST_SUBSCRIPTIONS]: funcs.listSubscriptions, [TOOL_METHODS.CANCEL_SUBSCRIPTION]: funcs.cancelSubscription, [TOOL_METHODS.PAUSE_SUBSCRIPTION]: funcs.pauseSubscription, [TOOL_METHODS.RESUME_SUBSCRIPTION]: funcs.resumeSubscription, [TOOL_METHODS.ACTIVATE_SUBSCRIPTION]: funcs.activateSubscription, [TOOL_METHODS.PREVIEW_SUBSCRIPTION_UPDATE]: funcs.previewSubscriptionUpdate, [TOOL_METHODS.CREATE_SUBSCRIPTION_CHARGE]: funcs.createSubscriptionCharge, [TOOL_METHODS.PREVIEW_SUBSCRIPTION_CHARGE]: funcs.previewSubscriptionCharge, [TOOL_METHODS.LIST_REPORTS]: funcs.listReports, [TOOL_METHODS.CREATE_REPORT]: funcs.createReport, [TOOL_METHODS.GET_REPORT]: funcs.getReport, [TOOL_METHODS.GET_REPORT_CSV]: funcs.getReportCsv, [TOOL_METHODS.LIST_CLIENT_SIDE_TOKENS]: funcs.listClientSideTokens, [TOOL_METHODS.CREATE_CLIENT_SIDE_TOKEN]: funcs.createClientSideToken, [TOOL_METHODS.GET_CLIENT_SIDE_TOKEN]: funcs.getClientSideToken, [TOOL_METHODS.REVOKE_CLIENT_SIDE_TOKEN]: funcs.revokeClientSideToken, }; - src/constants.ts:75-75 (helper)Constant definition for the tool method name string used across registrations and mappings.
CREATE_SUBSCRIPTION_CHARGE: "create_subscription_charge", - src/tools.ts:617-617 (schema)Reference to the Zod schema for input parameters used for validation in both tool registration and handler type inference.
parameters: params.createSubscriptionChargeParameters,