> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# GET /simulations

**List simulations**

Returns a paginated list of simulations. Use the query parameters to [page through results](https://developer.paddle.com/api-reference/about/pagination).

**Required permissions:** `notification_simulation.read`

## Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | array | optional | Return only the IDs specified. Use a comma-separated list to get multiple entities. |
| `after` | string | optional | 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_page` | integer | optional | 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; default: `50`) |
| `notification_setting_id` | array | optional | Return entities related to the specified notification destination. Use a comma-separated list to specify multiple notification destination IDs. |
| `order_by` | string | optional | Order returned entities by the specified field and direction (`[ASC]` or `[DESC]`). For example, `?order_by=id[ASC]`.

Valid fields for ordering: `id`. (default: `"id[DESC]"`) |
| `status` | array | optional | Return entities that match the specified status. Use a comma-separated list to specify multiple status values. (default: `["active"]`) |

Values for `status`:

- `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.

## Response (200)

- `data`: array (required)
  - Single event — Single event simulations play a single event.
    - `id`: string (required) — Unique Paddle ID for this simulation, prefixed with `ntfsim_`. (pattern: `^ntfsim_[a-z\d]{26}$`)
    - `status`: string (required) — Whether this entity can be used in Paddle. (default: `"active"`)
      - `active` — Entity is active and can be used.
      - `archived` — Entity is archived, so can't be used.
    - `notification_setting_id`: string (required) — Paddle ID of the notification setting where this simulation is sent, prefixed with `ntfset_`. (pattern: `^ntfset_[a-z\d]{26}$`)
    - `name`: string (required) — Name of this simulation.
    - `type`: string (required) — Single event sent for this simulation, in the format `entity.event_type`.
      - `address.created` — An [`address.created`](https://developer.paddle.com/webhooks/addresses/address-created) event.
      - `address.imported` — An [`address.imported`](https://developer.paddle.com/webhooks/addresses/address-imported) event.
      - `address.updated` — An [`address.updated`](https://developer.paddle.com/webhooks/addresses/address-updated) event.
      - `adjustment.created` — An [`adjustment.created`](https://developer.paddle.com/webhooks/adjustments/adjustment-created) event.
      - `adjustment.updated` — An [`adjustment.updated`](https://developer.paddle.com/webhooks/adjustments/adjustment-updated) event.
      - `api_key.created` — An [`api_key.created`](https://developer.paddle.com/webhooks/api-keys/api-key-created) event.
      - `api_key.expired` — An [`api_key.expired`](https://developer.paddle.com/webhooks/api-keys/api-key-expired) event.
      - `api_key.expiring` — An [`api_key.expiring`](https://developer.paddle.com/webhooks/api-keys/api-key-expiring) event.
      - `api_key.revoked` — An [`api_key.revoked`](https://developer.paddle.com/webhooks/api-keys/api-key-revoked) event.
      - `api_key.updated` — An [`api_key.updated`](https://developer.paddle.com/webhooks/api-keys/api-key-updated) event.
      - `api_key_exposure.created` — An [`api_key_exposure.created`](https://developer.paddle.com/webhooks/api-key-exposures/api-key-exposure-created) event.
      - `business.created` — A [`business.created`](https://developer.paddle.com/webhooks/businesses/business-created) event.
      - `business.imported` — A [`business.imported`](https://developer.paddle.com/webhooks/businesses/business-imported) event.
      - `business.updated` — A [`business.updated`](https://developer.paddle.com/webhooks/businesses/business-updated) event.
      - `client_token.created` — A [`client_token.created`](https://developer.paddle.com/webhooks/client-tokens/client-token-created) event.
      - `client_token.revoked` — A [`client_token.revoked`](https://developer.paddle.com/webhooks/client-tokens/client-token-revoked) event.
      - `client_token.updated` — A [`client_token.updated`](https://developer.paddle.com/webhooks/client-tokens/client-token-updated) event.
      - `customer.created` — A [`customer.created`](https://developer.paddle.com/webhooks/customers/customer-created) event.
      - `customer.imported` — A [`customer.imported`](https://developer.paddle.com/webhooks/customers/customer-imported) event.
      - `customer.updated` — A [`customer.updated`](https://developer.paddle.com/webhooks/customers/customer-updated) event.
      - `discount.created` — A [`discount.created`](https://developer.paddle.com/webhooks/discounts/discount-created) event.
      - `discount.imported` — A [`discount.imported`](https://developer.paddle.com/webhooks/discounts/discount-imported) event.
      - `discount.updated` — A [`discount.updated`](https://developer.paddle.com/webhooks/discounts/discount-updated) event.
      - `discount_group.created` — A [`discount_group.created`](https://developer.paddle.com/webhooks/discount-groups/discount-group-created) event.
      - `discount_group.updated` — A [`discount_group.updated`](https://developer.paddle.com/webhooks/discount-groups/discount-group-updated) event.
      - `payment_method.saved` — A [`payment_method.saved`](https://developer.paddle.com/webhooks/payment-methods/payment-method-saved) event.
      - `payment_method.deleted` — A [`payment_method.deleted`](https://developer.paddle.com/webhooks/payment-methods/payment-method-deleted) event.
      - `payout.created` — A [`payout.created`](https://developer.paddle.com/webhooks/payouts/payout-created) event.
      - `payout.paid` — A [`payout.paid`](https://developer.paddle.com/webhooks/payouts/payout-paid) event.
      - `price.created` — A [`price.created`](https://developer.paddle.com/webhooks/prices/price-created) event.
      - `price.imported` — A [`price.imported`](https://developer.paddle.com/webhooks/prices/price-imported) event.
      - `price.updated` — A [`price.updated`](https://developer.paddle.com/webhooks/prices/price-updated) event.
      - `product.created` — A [`product.created`](https://developer.paddle.com/webhooks/products/product-created) event.
      - `product.imported` — A [`product.imported`](https://developer.paddle.com/webhooks/products/product-imported) event.
      - `product.updated` — A [`product.updated`](https://developer.paddle.com/webhooks/products/product-updated) event.
      - `report.created` — A [`report.created`](https://developer.paddle.com/webhooks/reports/report-created) event.
      - `report.updated` — A [`report.updated`](https://developer.paddle.com/webhooks/reports/report-updated) event.
      - `subscription.activated` — A [`subscription.activated`](https://developer.paddle.com/webhooks/subscriptions/subscription-activated) event.
      - `subscription.canceled` — A [`subscription.canceled`](https://developer.paddle.com/webhooks/subscriptions/subscription-canceled) event.
      - `subscription.created` — A [`subscription.created`](https://developer.paddle.com/webhooks/subscriptions/subscription-created) event.
      - `subscription.imported` — A [`subscription.imported`](https://developer.paddle.com/webhooks/subscriptions/subscription-imported) event.
      - `subscription.past_due` — A [`subscription.past_due`](https://developer.paddle.com/webhooks/subscriptions/subscription-past-due) event.
      - `subscription.paused` — A [`subscription.paused`](https://developer.paddle.com/webhooks/subscriptions/subscription-paused) event.
      - `subscription.resumed` — A [`subscription.resumed`](https://developer.paddle.com/webhooks/subscriptions/subscription-resumed) event.
      - `subscription.trialing` — A [`subscription.trialing`](https://developer.paddle.com/webhooks/subscriptions/subscription-trialing) event.
      - `subscription.updated` — A [`subscription.updated`](https://developer.paddle.com/webhooks/subscriptions/subscription-updated) event.
      - `transaction.billed` — A [`transaction.billed`](https://developer.paddle.com/webhooks/transactions/transaction-billed) event.
      - `transaction.canceled` — A [`transaction.canceled`](https://developer.paddle.com/webhooks/transactions/transaction-canceled) event.
      - `transaction.completed` — A [`transaction.completed`](https://developer.paddle.com/webhooks/transactions/transaction-completed) event.
      - `transaction.created` — A [`transaction.created`](https://developer.paddle.com/webhooks/transactions/transaction-created) event.
      - `transaction.paid` — A [`transaction.paid`](https://developer.paddle.com/webhooks/transactions/transaction-paid) event.
      - `transaction.past_due` — A [`transaction.past_due`](https://developer.paddle.com/webhooks/transactions/transaction-past-due) event.
      - `transaction.payment_failed` — A [`transaction.payment_failed`](https://developer.paddle.com/webhooks/transactions/transaction-payment-failed) event.
      - `transaction.ready` — A [`transaction.ready`](https://developer.paddle.com/webhooks/transactions/transaction-ready) event.
      - `transaction.revised` — A [`transaction.revised`](https://developer.paddle.com/webhooks/transactions/transaction-revised) event.
      - `transaction.updated` — A [`transaction.updated`](https://developer.paddle.com/webhooks/transactions/transaction-updated) event.
    - `payload`: object | null (required) — Simulation payload.
    - `config`: null (required) — Configuration for scenario simulations. `null` for single events.
    - `last_run_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this simulation was last run. `null` until run. Set automatically by Paddle.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — 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.
    - `id`: string (required) — Unique Paddle ID for this simulation, prefixed with `ntfsim_`. (pattern: `^ntfsim_[a-z\d]{26}$`)
    - `status`: string (required) — Whether this entity can be used in Paddle. (default: `"active"`)
      - `active` — Entity is active and can be used.
      - `archived` — Entity is archived, so can't be used.
    - `notification_setting_id`: string (required) — Paddle ID of the notification setting where this simulation is sent, prefixed with `ntfset_`. (pattern: `^ntfset_[a-z\d]{26}$`)
    - `name`: string (required) — Name of this simulation.
    - `type`: string (required) — Scenario for this simulation. Scenario simulations play all events sent for a subscription lifecycle event.
      - `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.
    - `payload`: null (required) — Simulation payload. `null` for scenarios.
    - `config`: object | null (required) — Configuration for this scenario simulation. Determines which granular flow is simulated and what entities are used to populate webhook payloads with.
      - `subscription_cancellation`: object | null (required) — Configuration for subscription canceled simulations.
        - `entities`: object (required) — Adds details of existing Paddle entities to webhook payloads sent in the simulation.
          - `subscription_id`: string | null (required) — Paddle ID of a subscription to simulate as canceled. Adds details of that subscription to webhook payloads. (pattern: `^sub_[a-z\d]{26}$`)
        - `options`: object (required) — Options that determine which webhooks are sent as part of a simulation.
          - `effective_from`: string (required) — Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to `immediately`. (default: `"immediately"`)
            - `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_transaction`: boolean (required) — 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`. (default: `false`)
      - `subscription_creation`: object | null (required) — Configuration for subscription creation simulations.
        - `entities`: object (required) — Adds details of existing Paddle entities to webhook payloads sent in the simulation.
          - `customer_id`: string | null (required) — Paddle ID of a customer. Adds customer details to webhook payloads. (pattern: `^ctm_[a-z\d]{26}$`)
          - `address_id`: string | null (required) — Paddle ID of an address. Adds address details to webhook payloads. Requires `customer_id`. (pattern: `^add_[a-z\d]{26}$`)
          - `business_id`: string | null (required) — Paddle ID of a business. Adds business details to webhook payloads. Requires `customer_id`. (pattern: `^biz_[a-z\d]{26}$`)
          - `payment_method_id`: string | null (required) — Paddle ID of a payment method. Adds payment method details to webhook payloads. Requires `customer_id`. (pattern: `^paymtd_[a-z\d]{26}$`)
          - `discount_id`: string | null (required) — 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_id`: string | null (required) — Paddle ID of a transaction. Bases the subscription on the transaction. (pattern: `^txn_[a-z\d]{26}$`)
          - `items`: array | null (required) — 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.
            - `quantity`: integer (required) — Quantity to bill for. (Min: 1)
            - `price_id`: string (required) — Paddle ID of an an existing catalog price to bill for. (pattern: `^pri_[a-z\d]{26}$`)
        - `options`: object (required) — Options that determine which webhooks are sent as part of a simulation.
          - `customer_simulated_as`: string (required) — 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`. (default: `"new"`)
            - `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_as`: string (required) — Determines which webhooks are sent based on whether a new, existing, or no business was provided. If omitted, defaults to `not_provided`. (default: `"not_provided"`)
            - `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_as`: string (required) — Determines which webhooks are sent based on whether a discount is used and how it's entered. If omitted, defaults to `not_provided`. (default: `"not_provided"`)
            - `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_pause`: object | null (required) — Configuration for subscription paused simulations.
        - `entities`: object (required) — Adds details of existing Paddle entities to webhook payloads sent in the simulation.
          - `subscription_id`: string | null (required) — Paddle ID of a subscription to simulate as paused. Adds details of that subscription to webhook payloads. (pattern: `^sub_[a-z\d]{26}$`)
        - `options`: object (required) — Options that determine which webhooks are sent as part of a simulation.
          - `effective_from`: string (required) — Determines which webhooks are sent based on when the subscription is paused or canceled. If omitted, defaults to `immediately`. (default: `"immediately"`)
            - `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_transaction`: boolean (required) — 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`. (default: `false`)
      - `subscription_renewal`: object | null (required) — Configuration for subscription renewed simulations.
        - `entities`: object (required) — Adds details of existing Paddle entities to webhook payloads sent in the simulation.
          - `subscription_id`: string | null (required) — Paddle ID of a subscription to simulate as renewed. Adds details of that subscription to webhook payloads. (pattern: `^sub_[a-z\d]{26}$`)
        - `options`: object (required) — Options that determine which webhooks are sent as part of a simulation.
          - `payment_outcome`: string (required) — Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to `success`. (default: `"success"`)
            - `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_action`: string | null (required) — 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`. (default: `null`)
            - `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_resume`: object | null (required) — Configuration for subscription resumed simulations.
        - `entities`: object (required) — Adds details of existing Paddle entities to webhook payloads sent in the simulation.
          - `subscription_id`: string | null (required) — Paddle ID of a subscription to simulate as resumed. Adds details of that subscription to webhook payloads. (pattern: `^sub_[a-z\d]{26}$`)
        - `options`: object (required) — Options that determine which webhooks are sent as part of a simulation.
          - `payment_outcome`: string (required) — Determines which webhooks are sent based on the outcome of the payment. If omitted, defaults to `success`. (default: `"success"`)
            - `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_action`: string | null (required) — 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`. (default: `null`)
            - `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_at`: string (date-time) | null (required) — RFC 3339 datetime string of when this simulation was last run. `null` until run. Set automatically by Paddle.
    - `created_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was created. Set automatically by Paddle.
    - `updated_at`: string (date-time) (required) — RFC 3339 datetime string of when this entity was updated. Set automatically by Paddle.
- `meta`: object (required) — Information about this response.
  - `request_id`: string (required) — Unique ID for the request relating to this response. Provide this when contacting Paddle support about a specific request.
  - `pagination`: object (required) — Keys used for working with paginated results.
    - `per_page`: integer (required) — Number of entities per page for this response. May differ from the number requested if the requested number is greater than the maximum.
    - `next`: string (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_more`: boolean (required) — Whether this response has another page.
    - `estimated_total`: integer — 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 example

```json
{
  "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"
  }
}
```