create_simulation
Create test webhook simulations for Paddle notification settings to validate webhook implementations before sending real events, supporting single events or subscription scenarios.
Instructions
This tool will create a new simulation for a notification setting (notification destination) in Paddle.
Test webhooks can be sent through the webhook simulator in the dashboard or via the API by creating and running a simulation. Simulations configure which test webhooks are sent by Paddle when run. They can simulate the sending of single events or scenarios which send multiple events, like subscription renewals or cancellations. This is ideal for testing webhook implementations and validating data before sending real events. If implementing webhooks or making changes to an implementation, create and run a simulation prior to sending real events.
For scenario simulations (type of subscription_creation, subscription_renewal, subscription_pause, subscription_resume, subscription_cancellation), config objects can be provided. The config object contains a key matching the scenario type (e.g., for type "subscription_creation", use config.subscription_creation). This nested object can contain entities and options fields to control which webhooks are sent and populate payloads with real entity data. If provided, the config object must match the scenario type selected.
Option values for scenario simulations:
subscriptionCancellation and subscriptionPause:
options.effectiveFrom:
next_billing_period: Simulates as if the subscription cancels or pauses at the start of next billing period.
immediately: Simulates as if the subscription cancels or pauses immediately.
subscriptionResume and subscriptionRenewal:
options.paymentOutcome:
success: Simulates as if the payment for the subscription is successful.
recovered_existing_payment_method: Simulates as if the payment for the subscription fails initially and the payment is recovered when retrying the existing payment method.
recovered_updated_payment_method: Simulates as if the payment for the subscription fails initially and the customer updates their payment method to successfully pay.
failed: Simulates as if the payment for the subscription is unsuccessful after all payment recovery attempts are exhausted.
options.dunningExhaustedAction (only valid when paymentOutcome is "failed"):
subscription_paused: Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
subscription_canceled: Simulates as if the subscription is canceled after all payment recovery attempts are exhausted.
subscriptionCreation:
options.customerSimulatedAs:
new: Simulates as if a new customer enters their details at checkout and Paddle creates a new customer.
existing_email_matched: Simulates as if an existing customer enters their details at checkout. Paddle matches it to an existing customer based on the email supplied and creates a new address for that customer.
existing_details_prefilled: Simulates as if existing customer details are prefilled at checkout by passing them to Paddle.js.
options.businessSimulatedAs:
not_provided: Simulates as if no business is provided.
new: Simulates as if a customer enters their business details at checkout and Paddle creates a new business.
existing_details_prefilled: Simulates as if an existing business is prefilled at checkout by passing it to Paddle.js.
options.discountSimulatedAs:
not_provided: Simulates as if no discount is entered.
prefilled: Simulates as if a discount is prefilled at checkout by passing it to Paddle.js. Requires entities.discountId.
entered_by_customer: Simulates as if a customer entered a discount at checkout. Requires entities.discountId.
If config.entities are not provided, simulated webhook payloads are populated with static demo examples.
If successful, the response includes a copy of the new simulation entity. The simulation can then be run to send the events to the notification destination with the create_simulation_run tool.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| notificationSettingId | Yes | Paddle ID of the notification setting (destination) where this simulation is sent, prefixed with `ntfset_`. | |
| name | Yes | Name of this simulation to identify internally. | |
| type | Yes | Type of event sent by Paddle, in the format `entity.event_type`. Either single events (e.g. 'subscription.created') or scenarios for multiple events (e.g. 'subscription_creation'). | |
| payload | No | Simulation payload. Pass a JSON object that matches the schema for an event type to simulate a custom payload. If omitted, Paddle populates with a demo example. Only for single event simulations, not scenarios. | |
| config | No | Configuration for this scenario simulation. Determines which granular flow is simulated and what entities are used to populate webhook payloads with. |
Implementation Reference
- src/functions.ts:575-586 (handler)The main handler function that implements the logic for the 'create_simulation' tool. It takes a Paddle instance and parameters, then calls paddle.simulations.create to create the simulation.
export const createSimulation = async ( paddle: Paddle, params: z.infer<typeof Parameters.createSimulationParameters>, ) => { try { // eslint-disable-next-line @typescript-eslint/no-explicit-any const simulation = await paddle.simulations.create(params as any); return simulation; } catch (error) { return error; } }; - src/api.ts:56-56 (registration)Registers the 'create_simulation' tool method to its handler function in the toolMap used by PaddleAPI to dispatch calls.
[TOOL_METHODS.CREATE_SIMULATION]: funcs.createSimulation, - src/tools.ts:818-828 (schema)Defines the tool specification including method name, description, input parameters schema reference (params.createSimulationParameters), and required actions for the 'create_simulation' tool.
method: "create_simulation", name: "Create a simulation", description: prompts.createSimulationPrompt, parameters: params.createSimulationParameters, actions: { simulations: { write: true, create: true, }, }, }, - src/constants.ts:48-48 (registration)Defines the constant string identifier for the 'create_simulation' tool method used across the codebase.
CREATE_SIMULATION: "create_simulation",