Docs

Get a simulation

Returns a simulation using its ID.

GET /simulations/{simulation_id}
Returns a simulation using its ID.

Requires notification_simulation.read permission.

Path parameters

simulation_idstringrequired
Paddle ID of the simulation entity to work with.

Response (200)

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. A JSON object that matches the schema for an event type.
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.
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
Unique Paddle ID for this subscription entity, prefixed with sub_.
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
Unique Paddle ID for this customer entity, prefixed with ctm_.
Pattern: ^ctm_[a-z\d]{26}$
address_idstring | nullrequired
Example: add_01gm302t81w94gyjpjpqypkzkf
Unique Paddle ID for this address entity, prefixed with add_.
Pattern: ^add_[a-z\d]{26}$
business_idstring | nullrequired
Example: biz_01grrebrzaee2qj2fqqhmcyzaj
Unique Paddle ID for this business entity, prefixed with biz_.
Pattern: ^biz_[a-z\d]{26}$
payment_method_idstring | nullrequired
Example: paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1
Unique Paddle ID for this payment method entity, prefixed with paymtd_.
Pattern: ^paymtd_[a-z\d]{26}$
discount_idstring | nullrequired
Example: dsc_01gv5kpg05xp104ek2fmgjwttf
Unique Paddle ID for this discount, prefixed with dsc_.
Pattern: ^dsc_[a-z\d]{26}$
transaction_idstring | nullrequired
Example: txn_01h04vsbhqc62t8hmd4z3b578c
Unique Paddle ID for this transaction entity, prefixed with txn_.
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
Unique Paddle ID for this subscription entity, prefixed with sub_.
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
Unique Paddle ID for this subscription entity, prefixed with sub_.
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
Unique Paddle ID for this subscription entity, prefixed with sub_.
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.
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.
Response
{
  "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"
  }
}

Was this page helpful?