> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).
>
> To search these docs, send a `GET` request to `https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question>` with a URL-encoded question. No authentication needed. It returns a JSON array of `{content, source_url}`, most relevant first.

# GET /simulations/{simulation_id}

**Get a simulation**

Returns a simulation using its ID.

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

## Path parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `simulation_id` | string | required | Paddle ID of the simulation entity to work with. |

## Response (200)

- `data` (required) — Represents a simulation entity.
  - 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.
      - `api_key_rotation.created` — An [`api_key_rotation.created`](https://developer.paddle.com/webhooks/api-key-rotations/api-key-rotation-created) event.
      - `api_key_rotation.updated` — An [`api_key_rotation.updated`](https://developer.paddle.com/webhooks/api-key-rotations/api-key-rotation-updated) 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.
      - `meter.created` (early access) — A [`meter.created`](https://developer.paddle.com/webhooks/meters/meter-created) event.
      - `meter.updated` (early access) — A [`meter.updated`](https://developer.paddle.com/webhooks/meters/meter-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.
      - `usage_balance.depleted` (early access) — A [`usage_balance.depleted`](https://developer.paddle.com/webhooks/usage-balances/usage-balance-depleted) 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.

### Response example

```json
{
  "data": {
    "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": {
    "request_id": "3db61fbc-dde6-4a33-9ac1-c2c781e569fc"
  }
}
```
