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
Docs

List simulations

Returns a paginated list of simulations.

GET /simulations
Returns a paginated list of simulations. Use the query parameters to page through results.

Query parameters

idarray
Return only the IDs specified. Use a comma-separated list to get multiple entities.
afterstring
Return entities after the specified Paddle ID when working with paginated endpoints. Used in the meta.pagination.next URL in responses for list operations.
per_pageinteger
Default: 50

Set how many entities are returned per page. Paddle returns the maximum number of results if a number greater than the maximum is requested. Check meta.pagination.per_page in the response to see how many were returned.

Default: 50; Maximum: 200.

Max: 200
notification_setting_idarray
Return entities related to the specified notification destination. Use a comma-separated list to specify multiple notification destination IDs.
order_bystring
Default: id[DESC]

Order returned entities by the specified field and direction ([ASC] or [DESC]). For example, ?order_by=id[ASC].

Valid fields for ordering: id.

statusarray
Default: active
Return entities that match the specified status. Use a comma-separated list to specify multiple status values.
Values
  • active
    Return entities where the status is active. Returned entities can be used in Paddle and are returned when listing entities.
  • archived
    Return entities where the status is archived. Returned entities can't be used for billing and aren't returned when listing entities.

Header parameters

Skip-Countstring
Set to true to skip the count query on list operations. When set, meta.pagination.estimated_total returns -1 instead of an exact count.

Response (200)

dataarrayrequired
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.
paginationobjectrequired
Keys used for working with paginated results.
per_pageintegerrequired
Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
nextstring (uri)required
URL containing the query parameters of the original request, along with the after parameter that marks the starting point of the next page. Always returned, even if has_more is false.
has_morebooleanrequired
Whether this response has another page.
estimated_totalinteger
Example: 999

Estimated number of entities for this response.

For datasets with 100,000 or fewer matches, returns the exact count. For datasets with more than 100,000 matches, returns 100001 to indicate that more than 100,000 entities match. Returns -1 when counting is skipped or couldn't be calculated.

Use has_more and next to page through all results rather than relying on estimated_total for an exact count.

Response
{
  "data": [
    {
      "id": "ntfsim_01j82fs5pvrdse93e1kawqy2fr",
      "notification_setting_id": "ntfset_01j8259dtga48jwekrv2pmk0kp",
      "name": "Refund or chargeback created",
      "type": "adjustment.created",
      "status": "active",
      "payload": null,
      "config": null,
      "last_run_at": "2024-09-18T11:55:18.261049Z",
      "created_at": "2024-09-18T11:55:15.547675Z",
      "updated_at": "2024-09-18T11:55:18.261225Z"
    },
    {
      "id": "ntfsim_01j82d9tc19c67jds5vzbzjcns",
      "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
      "name": "Subscription created using pricing page on website",
      "type": "subscription_creation",
      "status": "active",
      "payload": null,
      "config": {
        "subscription_cancellation": null,
        "subscription_creation": {
          "entities": {
            "customer_id": null,
            "address_id": null,
            "business_id": null,
            "payment_method_id": null,
            "discount_id": null,
            "transaction_id": null,
            "items": null
          },
          "options": {
            "customer_simulated_as": "existing_email_matched",
            "business_simulated_as": "not_provided",
            "discount_simulated_as": "not_provided"
          }
        },
        "subscription_pause": null,
        "subscription_renewal": null,
        "subscription_resume": null
      },
      "last_run_at": null,
      "created_at": "2024-09-18T11:11:55.265125Z",
      "updated_at": "2024-09-18T11:54:18.543265Z"
    }
  ],
  "meta": {
    "pagination": {
      "per_page": 50,
      "estimated_total": 2,
      "next": "https://api.paddle.dev/simulations?after=ntfsim_01j55cce7pz60k2a4dfeh1c9sa",
      "has_more": false
    },
    "request_id": "ad095054-41bc-4907-907d-da18310aea49"
  }
}

Was this page helpful?