[ Web Proxy ]
URL:
Viewing: https://developer.paddle.com/api-reference/simulations/create-simulation [Back]  [Original]
Create a simulation | Paddle Developer Docs

For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling append .md to any URL.

Skip to content
Paddle Docs home
Search Ask AI Toggle Theme svg]:px-3 hidden md:flex" href="https://login.paddle.com/start" data-auth-button="true" data-login-url="https://login.paddle.com/start" data-dashboard-url="https://vendors.paddle.com" data-dashboard-api="https://api.paddle.com/userinfo" data-astro-cid-mq3pp5jd="true"> Login

API reference

Overview
Home
API reference
Simulations
svg]:px-2.5 h-8 gap-2 shadow-none md:h-7 md:text-[0.8rem]" href="https://god.gw.postman.com/run-collection/29428794-16aca740-3ad6-4c1a-97be-05dbc504b4c3?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D29428794-16aca740-3ad6-4c1a-97be-05dbc504b4c3%26entityType%3Dcollection%26workspaceId%3D5ed2587a-f47e-43e0-810c-0c3e782bca12#?env%5BSandbox%5D=W3sia2V5IjoiYmFzZVVybCIsInZhbHVlIjoiaHR0cHM6Ly9zYW5kYm94LWFwaS5wYWRkbGUuY29tIiwiZW5hYmxlZCI6dHJ1ZSwidHlwZSI6ImRlZmF1bHQifSx7ImtleSI6ImJlYXJlclRva2VuIiwidmFsdWUiOiIiLCJlbmFibGVkIjp0cnVlLCJ0eXBlIjoic2VjcmV0In1d" target="_blank" rel="noopener noreferrer" title="Fork the Paddle Postman collection" data-postman-run-button="true" data-astro-cid-6ac4p433="true">

Create a simulation

Creates a new simulation for a notification setting (notification destination).

POST /simulations

Creates a new simulation for a notification setting (notification destination).

simulated webhook payloads with real data. The API key making the request needs read permissions:

  • For the entities you provided, or the request fails.
  • For related entities which aren't nested in the entities you provided, or static examples will be used instead.

For example, when creating a subscription renewal scenario simulation with an API key that has a subscription.read permission but not a transaction.read permission, the request succeeds and the subscription data will be used in simulated payloads, but the related transaction data won't be used in payloads and falls back to a static example.

If you don't provide a config.entities object, simulated webhook payloads are populated with static examples.

If successful, your response includes a copy of the new simulation entity.

Requires notification_simulation.write permission.

Request body

Single event
Represents a simulation entity for a single event when creating.
namestringrequired
Name of this simulation.
typestringrequired
Single event sent for this simulation, in the format entity.event_type.
Values
+ Show all values
payloadobject | null
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.
Scenario
Represents a simulation entity for a scenario when creating.
namestringrequired
Name of this simulation.
typestringrequired
Scenario for this simulation. Scenario simulations play all events sent for a subscription lifecycle event.
Values
  • subscription_creation
    Simulates all events sent when a subscription is created.
  • subscription_renewal
    Simulates all events sent when a subscription is renewed.
  • subscription_pause
    Simulates all events sent when a subscription is paused.
  • subscription_resume
    Simulates all events sent when a subscription is resumed.
  • subscription_cancellation
    Simulates all events sent when a subscription is canceled.
config
Configuration for this scenario simulation. Use to simulate more granular flows and populate payloads with your own entity data. If omitted, Paddle simulates the default scenario flow and populates payloads with demo examples.
Subscription cancellation config
Configuration for subscription canceled simulations.
subscription_cancellationobject
Configuration for subscription canceled simulations.
entitiesobject
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | null
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as canceled. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobject
Options that determine which webhooks are sent as part of a simulation.
effective_fromstring
Default: immediately
Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to immediately.
Values
  • next_billing_period
    Simulates as if the subscription cancels at the start of next billing period.
  • immediately
    Simulates as if the subscription cancels immediately.
has_past_due_transactionboolean
Default: false
Whether a simulated subscription has a past due transaction (true) or not (false), which determines whether events occur for canceling past due transactions. If omitted, defaults to false.
Subscription creation config
Configuration for subscription creation simulations.
subscription_creationobject
Configuration for subscription creation simulations.
entities
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
Subscription creation config without prices
Configuration resources for subscription creation simulations
customer_idstring | null
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of a customer. Adds customer details to webhook payloads.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | null
Example: add_01gm302t81w94gyjpjpqypkzkf
Paddle ID of an address. Adds address details to webhook payloads. Requires customer_id.
Pattern: ^add_[a-z\d]{26}$
business_idstring | null
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Paddle ID of a business. Adds business details to webhook payloads. Requires customer_id.
Pattern: ^biz_[a-z\d]{26}$
payment_method_idstring | null
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Paddle ID of a payment method. Adds payment method details to webhook payloads. Requires customer_id.
Pattern: ^paymtd_[a-z\d]{26}$
discount_idstring | null
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Paddle ID of an existing discount to apply to the simulated subscription.
Pattern: ^dsc_[a-z\d]{26}$
itemsnull
Items for the simulated subscription. Only existing products and prices can be simulated. Non-catalog items are not supported
transaction_idnull
Paddle ID of an existing transaction. Simulates passing a transaction ID to Paddle.js.
Subscription creation config for items
Configuration resources for subscription creation simulations with items
customer_idstring | null
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of a customer. Adds customer details to webhook payloads.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | null
Example: add_01gm302t81w94gyjpjpqypkzkf
Paddle ID of an address. Adds address details to webhook payloads. Requires customer_id.
Pattern: ^add_[a-z\d]{26}$
business_idstring | null
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Paddle ID of a business. Adds business details to webhook payloads. Requires customer_id.
Pattern: ^biz_[a-z\d]{26}$
payment_method_idstring | null
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Paddle ID of a payment method. Adds payment method details to webhook payloads. Requires customer_id.
Pattern: ^paymtd_[a-z\d]{26}$
discount_idstring | null
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Paddle ID of a discount. Adds discount details (including price calculations) to webhook payloads. Requires items or transaction_id for the discount to be applied.
Pattern: ^dsc_[a-z\d]{26}$
itemsarray
Items to include on the simulated subscription. Only existing products and prices can be simulated. Non-catalog items aren't supported. At least one recurring price must be provided.
Items: 1100
quantityintegerrequired
Example: 5
Quantity to bill for.
Min: 1
price_idstringrequired
Example: pri_01gsz8z1q1n00f12qt82y31smh
Paddle ID of an an existing catalog price to bill for.
Pattern: ^pri_[a-z\d]{26}$
transaction_idnull
Paddle ID of an existing transaction. Simulates passing a transaction ID to Paddle.js.
Subscription creation config for transaction
Configuration resources for subscription creation simulations with existing transaction
customer_idstring | null
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of a customer. Adds customer details to webhook payloads.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | null
Example: add_01gm302t81w94gyjpjpqypkzkf
Paddle ID of an address. Adds address details to webhook payloads. Requires customer_id.
Pattern: ^add_[a-z\d]{26}$
business_idstring | null
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Paddle ID of a business. Adds business details to webhook payloads. Requires customer_id.
Pattern: ^biz_[a-z\d]{26}$
payment_method_idstring | null
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Paddle ID of a payment method. Adds payment method details to webhook payloads. Requires customer_id.
Pattern: ^paymtd_[a-z\d]{26}$
discount_idstring | null
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Paddle ID of a discount. Adds discount details (including price calculations) to webhook payloads. Requires items or transaction_id for the discount to be applied.
Pattern: ^dsc_[a-z\d]{26}$
transaction_idstring
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Paddle ID of a transaction. Bases the subscription from this transaction.
Pattern: ^txn_[a-z\d]{26}$
itemsnull
Items to include on the simulated subscription. Only existing products and prices can be simulated. Non-catalog items aren't supported. At least one recurring price must be provided.
optionsobject
Options that determine which webhooks are sent as part of a simulation.
customer_simulated_asstring
Default: new
Determines which webhooks are sent based on whether a new or existing customer subscribes, and how their details are entered if they're an existing customer. If omitted, defaults to new.
Values
  • 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.
business_simulated_asstring
Default: not_provided
Determines which webhooks are sent based on whether a new, existing, or no business was provided. If omitted, defaults to not_provided.
Values
  • 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.
discount_simulated_asstring
Default: not_provided
Determines which webhooks are sent based on whether a discount is used and how it's entered. If omitted, defaults to not_provided.
Values
  • 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.discount_id.
  • entered_by_customer
    Simulates as if a customer entered a discount at checkout. Requires entities.discount_id.
Subscription paused config
Configuration for subscription paused simulations.
subscription_pauseobject
Configuration for subscription paused simulations.
entitiesobject
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | null
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as paused. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobject
Options that determine which webhooks are sent as part of a simulation.
effective_fromstring
Default: immediately
Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to immediately.
Values
  • next_billing_period
    Simulates as if the subscription pauses at the start of next billing period.
  • immediately
    Simulates as if the subscription pauses immediately.
has_past_due_transactionboolean
Default: false
Whether a simulated subscription has a past due transaction (true) or not (false), which determines whether events occur for canceling past due transactions. If omitted, defaults to false.
Subscription renewal config
Configuration for subscription renewed simulations.
subscription_renewalobject
Configuration for subscription renewed simulations.
entitiesobject
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | null
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as renewed. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
options
Options that determine which webhooks are sent as part of a simulation.
Successful payment outcome options
Options for when the payment outcome is successful.
payment_outcomestring
Default: success
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • success
    Simulates as if the payment for the subscription is successful.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Failed payment outcome options
Options for when the payment outcome is failed.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • failed
    Simulates as if the payment for the subscription is unsuccessful after all payment recovery attempts are exhausted.
dunning_exhausted_actionstring
Default: subscription_canceled
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. If omitted, defaults to subscription_canceled.
Values
  • subscription_paused
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
  • subscription_canceled
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
Recovered from existing payment method payment outcome options
Options for when the payment is recovered from an existing payment method.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • 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.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Recovered from updated payment method payment outcome options
Options for when the payment is recovered from an updated payment method.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • recovered_updated_payment_method
    Simulates as if the payment for the subscription fails initially and the customer updates their payment method to successfully pay.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Subscription resume config
Configuration for subscription resumed simulations.
subscription_resumeobject
Configuration for subscription resumed simulations.
entitiesobject
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | null
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as resumed. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
options
Options that determine which webhooks are sent as part of a simulation.
Successful payment outcome options
Options for when the payment outcome is successful.
payment_outcomestring
Default: success
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • success
    Simulates as if the payment for the subscription is successful.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Failed payment outcome options
Options for when the payment outcome is failed.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • failed
    Simulates as if the payment for the subscription is unsuccessful after all payment recovery attempts are exhausted.
dunning_exhausted_actionstring
Default: subscription_canceled
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. If omitted, defaults to subscription_canceled.
Values
  • subscription_paused
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
  • subscription_canceled
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
Recovered from existing payment method payment outcome options
Options for when the payment is recovered from an existing payment method.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • 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.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Recovered from updated payment method payment outcome options
Options for when the payment is recovered from an updated payment method.
payment_outcomestring
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • recovered_updated_payment_method
    Simulates as if the payment for the subscription fails initially and the customer updates their payment method to successfully pay.
dunning_exhausted_actionnull
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.

Response (201)

datarequired
Represents a simulation entity.
Single event
Single event simulations play a single event.
idstringrequired
Example: ntfsim_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this simulation, prefixed with ntfsim_.
Pattern: ^ntfsim_[a-z\d]{26}$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
notification_setting_idstringrequired
Example: ntfset_01gt21c5pdx9q1e4mh1xrsjjn6
Paddle ID of the notification setting where this simulation is sent, prefixed with ntfset_.
Pattern: ^ntfset_[a-z\d]{26}$
namestringrequired
Name of this simulation.
typestringrequired
Single event sent for this simulation, in the format entity.event_type.
Values
+ Show all values
payloadobject | nullrequired
Simulation payload.
confignullrequired
Configuration for scenario simulations. null for single events.
last_run_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this simulation was last run. null until run. Set automatically by Paddle.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
Scenario
Scenario simulations play all events sent for a subscription lifecycle event.
idstringrequired
Example: ntfsim_01ghbkd0frb9k95cnhwd1bxpvk
Unique Paddle ID for this simulation, prefixed with ntfsim_.
Pattern: ^ntfsim_[a-z\d]{26}$
statusstringrequired
Default: active
Whether this entity can be used in Paddle.
Values
  • active
    Entity is active and can be used.
  • archived
    Entity is archived, so can't be used.
notification_setting_idstringrequired
Example: ntfset_01gt21c5pdx9q1e4mh1xrsjjn6
Paddle ID of the notification setting where this simulation is sent, prefixed with ntfset_.
Pattern: ^ntfset_[a-z\d]{26}$
namestringrequired
Name of this simulation.
typestringrequired
Scenario for this simulation. Scenario simulations play all events sent for a subscription lifecycle event.
Values
  • subscription_creation
    Simulates all events sent when a subscription is created.
  • subscription_renewal
    Simulates all events sent when a subscription is renewed.
  • subscription_pause
    Simulates all events sent when a subscription is paused.
  • subscription_resume
    Simulates all events sent when a subscription is resumed.
  • subscription_cancellation
    Simulates all events sent when a subscription is canceled.
payloadnullrequired
Simulation payload. null for scenarios.
configobject | nullrequired
Configuration for this scenario simulation. Determines which granular flow is simulated and what entities are used to populate webhook payloads with.
subscription_cancellationobject | nullrequired
Configuration for subscription canceled simulations.
entitiesobjectrequired
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as canceled. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobjectrequired
Options that determine which webhooks are sent as part of a simulation.
effective_fromstringrequired
Default: immediately
Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to immediately.
Values
  • next_billing_period
    Simulates as if the subscription cancels at the start of next billing period.
  • immediately
    Simulates as if the subscription cancels immediately.
has_past_due_transactionbooleanrequired
Default: false
Whether a simulated subscription has a past due transaction (true) or not (false), which determines whether events occur for canceling past due transactions. If omitted, defaults to false.
subscription_creationobject | nullrequired
Configuration for subscription creation simulations.
entitiesobjectrequired
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
customer_idstring | nullrequired
Example: ctm_01grnn4zta5a1mf02jjze7y2ys
Paddle ID of a customer. Adds customer details to webhook payloads.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | nullrequired
Example: add_01gm302t81w94gyjpjpqypkzkf
Paddle ID of an address. Adds address details to webhook payloads. Requires customer_id.
Pattern: ^add_[a-z\d]{26}$
business_idstring | nullrequired
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Paddle ID of a business. Adds business details to webhook payloads. Requires customer_id.
Pattern: ^biz_[a-z\d]{26}$
payment_method_idstring | nullrequired
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Paddle ID of a payment method. Adds payment method details to webhook payloads. Requires customer_id.
Pattern: ^paymtd_[a-z\d]{26}$
discount_idstring | nullrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Paddle ID of a discount. Adds discount details (including price calculations) to webhook payloads. Requires items or transaction_id for the discount to be applied.
Pattern: ^dsc_[a-z\d]{26}$
transaction_idstring | nullrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Paddle ID of a transaction. Bases the subscription on the transaction.
Pattern: ^txn_[a-z\d]{26}$
itemsarray | nullrequired
Items to include on the simulated subscription. Only existing products and prices can be simulated. Non-catalog items aren't supported. At least one recurring price must be provided.
quantityintegerrequired
Example: 5
Quantity to bill for.
Min: 1
price_idstringrequired
Example: pri_01gsz8z1q1n00f12qt82y31smh
Paddle ID of an an existing catalog price to bill for.
Pattern: ^pri_[a-z\d]{26}$
optionsobjectrequired
Options that determine which webhooks are sent as part of a simulation.
customer_simulated_asstringrequired
Default: new
Determines which webhooks are sent based on whether a new or existing customer subscribes, and how their details are entered if they're an existing customer. If omitted, defaults to new.
Values
  • 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.
business_simulated_asstringrequired
Default: not_provided
Determines which webhooks are sent based on whether a new, existing, or no business was provided. If omitted, defaults to not_provided.
Values
  • 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.
discount_simulated_asstringrequired
Default: not_provided
Determines which webhooks are sent based on whether a discount is used and how it's entered. If omitted, defaults to not_provided.
Values
  • 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.discount_id.
  • entered_by_customer
    Simulates as if a customer entered a discount at checkout. Requires entities.discount_id.
subscription_pauseobject | nullrequired
Configuration for subscription paused simulations.
entitiesobjectrequired
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as paused. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobjectrequired
Options that determine which webhooks are sent as part of a simulation.
effective_fromstringrequired
Default: immediately
Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to immediately.
Values
  • next_billing_period
    Simulates as if the subscription pauses at the start of next billing period.
  • immediately
    Simulates as if the subscription pauses immediately.
has_past_due_transactionbooleanrequired
Default: false
Whether a simulated subscription has a past due transaction (true) or not (false), which determines whether events occur for canceling past due transactions. If omitted, defaults to false.
subscription_renewalobject | nullrequired
Configuration for subscription renewed simulations.
entitiesobjectrequired
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as renewed. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobjectrequired
Options that determine which webhooks are sent as part of a simulation.
payment_outcomestringrequired
Default: success
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • 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.
dunning_exhausted_actionstring | nullrequired
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Values
  • subscription_paused
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
  • subscription_canceled
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
subscription_resumeobject | nullrequired
Configuration for subscription resumed simulations.
entitiesobjectrequired
Adds details of existing Paddle entities to webhook payloads sent in the simulation.
subscription_idstring | nullrequired
Example: sub_01h04vsc0qhwtsbsxh3422wjs4
Paddle ID of a subscription to simulate as resumed. Adds details of that subscription to webhook payloads.
Pattern: ^sub_[a-z\d]{26}$
optionsobjectrequired
Options that determine which webhooks are sent as part of a simulation.
payment_outcomestringrequired
Default: success
Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to success.
Values
  • 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.
dunning_exhausted_actionstring | nullrequired
Determines which webhooks are sent based on what happens to the subscription when payment recovery attempts are exhausted. Only applies when payment_outcome is failed. If omitted, defaults to null.
Values
  • subscription_paused
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
  • subscription_canceled
    Simulates as if the subscription is paused after all payment recovery attempts are exhausted.
last_run_atstring (date-time) | nullrequired
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this simulation was last run. null until run. Set automatically by Paddle.
created_atstring (date-time)required
Example: 2024-10-12T07:20:50.52Z
RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
updated_atstring (date-time)required
Example: 2024-10-13T07:20:50.52Z
RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
metaobjectrequired
Information about this response.
request_idstringrequired
Example: b15ec92e-8688-40d4-a04d-f44cbec93355
Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
Request Response
Request
{
  "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
  "name": "Create a failed subscription renewal simulation with subscription ID",
  "type": "subscription_renewal",
  "config": {
    "subscription_renewal": {
      "entities": {
        "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4"
      },
      "options": {
        "payment_outcome": "failed",
        "dunning_exhausted_action": "subscription_canceled"
      }
    }
  }
}
{ "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz", "name": "Create a failed subscription renewal simulation with subscription ID", "type": "subscription_renewal", "config": { "subscription_renewal": { "entities": { "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4" }, "options": { "payment_outcome": "failed", "dunning_exhausted_action": "subscription_canceled" } } } }
Response
{
  "data": {
    "id": "ntfsim_01j82g2mggsgjpb3mjg0xq6p5k",
    "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
    "name": "Create a subscription renewal simulation with config",
    "type": "subscription_renewal",
    "status": "active",
    "payload": null,
    "config": {
      "subscription_cancellation": null,
      "subscription_creation": null,
      "subscription_pause": null,
      "subscription_renewal": {
        "entities": {
          "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4"
        },
        "options": {
          "payment_outcome": "recovered_updated_payment_method",
          "dunning_exhausted_action": null
        }
      },
      "subscription_resume": null
    },
    "last_run_at": null,
    "created_at": "2024-09-18T12:00:25.616392Z",
    "updated_at": "2024-09-18T12:00:25.616392Z"
  },
  "meta": {
    "request_id": "72351248-13bf-45be-befe-b3a5b5234588"
  }
}
{ "data": { "id": "ntfsim_01j82g2mggsgjpb3mjg0xq6p5k", "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz", "name": "Create a subscription renewal simulation with config", "type": "subscription_renewal", "status": "active", "payload": null, "config": { "subscription_cancellation": null, "subscription_creation": null, "subscription_pause": null, "subscription_renewal": { "entities": { "subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4" }, "options": { "payment_outcome": "recovered_updated_payment_method", "dunning_exhausted_action": null } }, "subscription_resume": null }, "last_run_at": null, "created_at": "2024-09-18T12:00:25.616392Z", "updated_at": "2024-09-18T12:00:25.616392Z" }, "meta": { "request_id": "72351248-13bf-45be-befe-b3a5b5234588" } }

Was this page helpful?

Yes, helpfulNo, not helpfulI have feedback
Paddle home
Status Security Changelog LLM benchmark Blog Contact
RSS Feed Run in Postman GitHub LinkedIn Twitter YouTube
Privacy policy Terms Manage cookies

Paddle.com Market Ltd. 20122026

Web Proxy Viewer  |  New URL  |  Original Page