---
title: "Get a simulation"
method: GET
path: "/simulations/{simulation_id}"
tags: ["Simulations"]
---

# Get a simulation

`GET /simulations/{simulation_id}`

## Request

- Base URL: `https://sandbox-api.paddle.com`
- URL: `https://sandbox-api.paddle.com/simulations/{simulation_id}`
- Auth: HTTP bearer

Returns a simulation using its ID.

## Path parameters

- `simulation_id` string, required

## Response `200`

The request has succeeded.

- object
  - `data` union, required: Represents a simulation entity.
    - SimulationStandardEventsModel: Single event simulations play a single event.
      - `id` string, required: Unique Paddle ID for this simulation, prefixed with `ntfsim_`.
      - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle.
      - `notification_setting_id` string, required: Unique Paddle ID for this notification setting, prefixed with `ntfset_`.
      - `name` string, required: Name of this simulation.
      - `type` 'address.created' | 'address.imported' | 'address.updated' | 'adjustment.created' | 'adjustment.updated' | 'api_key.created' | 'api_key.expired' | 'api_key.expiring' | 'api_key.revoked' | 'api_key.updated' | 'api_key_exposure.created' | 'business.created' | 'business.imported' | 'business.updated' | 'client_token.created' | 'client_token.revoked' | 'client_token.updated' | 'customer.created' | 'customer.imported' | 'customer.updated' | 'discount.created' | 'discount.imported' | 'discount.updated' | 'discount_group.created' | 'discount_group.updated' | 'payment_method.saved' | 'payment_method.deleted' | 'payout.created' | 'payout.paid' | 'price.created' | 'price.imported' | 'price.updated' | 'product.created' | 'product.imported' | 'product.updated' | 'report.created' | 'report.updated' | 'subscription.activated' | 'subscription.canceled' | 'subscription.created' | 'subscription.imported' | 'subscription.past_due' | 'subscription.paused' | 'subscription.resumed' | 'subscription.trialing' | 'subscription.updated' | 'transaction.billed' | 'transaction.canceled' | 'transaction.completed' | 'transaction.created' | 'transaction.paid' | 'transaction.past_due' | 'transaction.payment_failed' | 'transaction.ready' | 'transaction.revised' | 'transaction.updated', required: Type of event sent by Paddle, in the format `entity.event_type`.
      - `payload` SimulationPayload, required: Simulation payload. A JSON object that matches the schema for an event type.
      - `config` unknown, required
      - `last_run_at` string, date-time, required: RFC 3339 datetime string.
      - `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.
    - SimulationScenarioEventsModel: Scenario simulations play all events sent for a subscription lifecycle event.
      - `id` string, required: Unique Paddle ID for this simulation, prefixed with `ntfsim_`.
      - `status` 'active' | 'archived', required: Whether this entity can be used in Paddle.
      - `notification_setting_id` string, required: Unique Paddle ID for this notification setting, prefixed with `ntfset_`.
      - `name` string, required: Name of this simulation.
      - `type` 'subscription_creation' | 'subscription_renewal' | 'subscription_pause' | 'subscription_resume' | 'subscription_cancellation', required: Scenario for a simulation.
      - `payload` unknown, required
      - `config` SimulationScenarioConfig, required: Configuration for this scenario simulation. Determines which granular flow is simulated and what entities are used to populate webhook payloads with.
        - `subscription_cancellation` SimulationConfigSubscriptionCancellation, required: Configuration for subscription canceled simulations.
          - `entities` SimulationConfigSubscriptionCancellationEntities, required: Adds details of existing Paddle entities to webhook payloads sent in the simulation.
            - `subscription_id` string, nullable, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
          - `options` SimulationConfigSubscriptionCancellationOptions, required: Options that determine which webhooks are sent as part of a simulation.
            - `effective_from` 'next_billing_period' | 'immediately', required
            - `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`.
        - `subscription_creation` SimulationConfigSubscriptionCreation, required: Configuration for subscription creation simulations.
          - `entities` SimulationConfigEntitiesSubscriptionCreation, required: Configuration resources for subscription creation simulations
            - `customer_id` string, nullable, required: Unique Paddle ID for this customer entity, prefixed with `ctm_`.
            - `address_id` string, nullable, required: Unique Paddle ID for this address entity, prefixed with `add_`.
            - `business_id` string, nullable, required: Unique Paddle ID for this business entity, prefixed with `biz_`.
            - `payment_method_id` string, nullable, required: Unique Paddle ID for this payment method entity, prefixed with `paymtd_`.
            - `discount_id` string, nullable, required: Unique Paddle ID for this discount, prefixed with `dsc_`.
            - `transaction_id` string, nullable, required: Unique Paddle ID for this transaction entity, prefixed with `txn_`.
            - `items` SubscriptionItemWithPriceId[], nullable, 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.
              - …
          - `options` SimulationConfigSubscriptionCreationOptions, required: Options to configure subscription creation simulations.
            - `customer_simulated_as` 'new' | 'existing_email_matched' | 'existing_details_prefilled', required
            - `business_simulated_as` 'not_provided' | 'new' | 'existing_details_prefilled', required
            - `discount_simulated_as` 'not_provided' | 'prefilled' | 'entered_by_customer', required
        - `subscription_pause` SimulationConfigSubscriptionPause, required: Configuration for subscription paused simulations.
          - `entities` SimulationConfigSubscriptionPauseEntities, required: Adds details of existing Paddle entities to webhook payloads sent in the simulation.
            - `subscription_id` string, nullable, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
          - `options` SimulationConfigSubscriptionPauseOptions, required: Options that determine which webhooks are sent as part of a simulation.
            - `effective_from` 'next_billing_period' | 'immediately', required
            - `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`.
        - `subscription_renewal` SimulationConfigSubscriptionRenewal, required: Configuration for subscription renewed simulations.
          - `entities` SimulationConfigSubscriptionRenewalEntities, required: Adds details of existing Paddle entities to webhook payloads sent in the simulation.
            - `subscription_id` string, nullable, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
          - `options` SimulationConfigOptionsPayment, required: Options to configure simulations based on the payment outcome.
            - `payment_outcome` 'success' | 'recovered_existing_payment_method' | 'recovered_updated_payment_method' | 'failed', required
            - `dunning_exhausted_action` 'subscription_paused' | 'subscription_canceled', required
        - `subscription_resume` SimulationConfigSubscriptionResume, required: Configuration for subscription resumed simulations.
          - `entities` SimulationConfigSubscriptionResumeEntities, required: Adds details of existing Paddle entities to webhook payloads sent in the simulation.
            - `subscription_id` string, nullable, required: Unique Paddle ID for this subscription entity, prefixed with `sub_`.
          - `options` SimulationConfigOptionsPayment, required: Options to configure simulations based on the payment outcome.
            - `payment_outcome` 'success' | 'recovered_existing_payment_method' | 'recovered_updated_payment_method' | 'failed', required
            - `dunning_exhausted_action` 'subscription_paused' | 'subscription_canceled', required
      - `last_run_at` string, date-time, required: RFC 3339 datetime string.
      - `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` Meta, 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.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-02-02** (v1) `9ba8be0f2006`: 8 breaking, 1 warning, 4 info
  - added the new path request parameter `simulation_id`
  - added `#/components/schemas/SimulationStandardEventsModel, #/components/schemas/SimulationScenarioEventsModel` to the `data` response property `oneOf` list for the response status `200`
  - the `data` response's property type changed from `object` to no type for status `200`
  - the `error` response's property type changed from `object` to no type for status `default`
  - …9 more
- **2025-05-27** (v1) `e57c515077cc`: 5 warning, 1 info
  - added the new `api_key.created` enum value to the `data/oneOf[subschema #1: Single event]/type` response property for the response status `200`
  - added the new `api_key.expired` enum value to the `data/oneOf[subschema #1: Single event]/type` response property for the response status `200`
  - added the new `api_key.expiring` enum value to the `data/oneOf[subschema #1: Single event]/type` response property for the response status `200`
  - added the new `api_key.revoked` enum value to the `data/oneOf[subschema #1: Single event]/type` response property for the response status `200`
  - …2 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/paddlehq/apis/paddle-api/changes/simulations/:simulation_id/get.md)

---

[API](https://skmtc.dev/paddlehq/apis/paddle-api.md) - [All operations](https://skmtc.dev/paddlehq/apis/paddle-api/llms.txt) - [OpenAPI document](https://skmtc.dev/paddlehq/apis/paddle-api/revisions/bbc0c72039c8?raw)