const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    notification_setting_id: 'ntfset_01j82d983j814ypzx7m1fw2jpz',
    name: 'New US address created for CRM',
    type: 'address.created',
    payload: {
      id: 'add_01hv8gq3318ktkfengj2r75gfx',
      city: 'New York',
      region: 'NY',
      status: 'active',
      created_at: '2024-04-12T06:42:58.785Z',
      first_line: '4050 Jefferson Plaza, 41st Floor',
      updated_at: '2024-04-12T06:42:58.785Z',
      custom_data: null,
      customer_id: 'ctm_01hv6y1jedq4p1n0yqn5ba3ky4',
      description: 'Head Office',
      import_meta: null,
      postal_code: '10021',
      second_line: null,
      country_code: 'US'
    }
  })
};

fetch('https://api.paddle.com/simulations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "ntfsim_01j82g2mggsgjpb3mjg0xq6p5k",
    "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
    "name": "New US address created for CRM",
    "type": "address.created",
    "status": "active",
    "payload": {
      "id": "add_01hv8gq3318ktkfengj2r75gfx",
      "city": "New York",
      "region": "NY",
      "status": "active",
      "created_at": "2024-04-12T06:42:58.785Z",
      "first_line": "4050 Jefferson Plaza, 41st Floor",
      "updated_at": "2024-04-12T06:42:58.785Z",
      "custom_data": null,
      "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "description": "Head Office",
      "import_meta": null,
      "postal_code": "10021",
      "second_line": null,
      "country_code": "US"
    },
    "last_run_at": null,
    "created_at": "2024-09-18T12:00:25.616392Z",
    "updated_at": "2024-09-18T12:00:25.616392Z"
  },
  "meta": {
    "request_id": "72351248-13bf-45be-befe-b3a5b5234588"
  }
}

Simulations

Create a simulation

Creates a new simulation for a notification setting (notification destination).

For scenario simulations, you can optionally include a config.entities object in the request body with entity IDs to populate simulated webhook payloads with real data. The API key making the request needs read permissions:

For the entities you provided, or the request fails.
For related entities which aren’t nested in the entities you provided, or static examples will be used instead.

For example, when creating a subscription renewal scenario simulation with an API key that has a subscription.read permission but not a transaction.read permission, the request succeeds and the subscription data will be used in simulated payloads, but the related transaction data won’t be used in payloads and falls back to a static example.

If you don’t provide a config.entities object, simulated webhook payloads are populated with static examples.

If successful, your response includes a copy of the new simulation entity.

POST

simulations

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    notification_setting_id: 'ntfset_01j82d983j814ypzx7m1fw2jpz',
    name: 'New US address created for CRM',
    type: 'address.created',
    payload: {
      id: 'add_01hv8gq3318ktkfengj2r75gfx',
      city: 'New York',
      region: 'NY',
      status: 'active',
      created_at: '2024-04-12T06:42:58.785Z',
      first_line: '4050 Jefferson Plaza, 41st Floor',
      updated_at: '2024-04-12T06:42:58.785Z',
      custom_data: null,
      customer_id: 'ctm_01hv6y1jedq4p1n0yqn5ba3ky4',
      description: 'Head Office',
      import_meta: null,
      postal_code: '10021',
      second_line: null,
      country_code: 'US'
    }
  })
};

fetch('https://api.paddle.com/simulations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "data": {
    "id": "ntfsim_01j82g2mggsgjpb3mjg0xq6p5k",
    "notification_setting_id": "ntfset_01j82d983j814ypzx7m1fw2jpz",
    "name": "New US address created for CRM",
    "type": "address.created",
    "status": "active",
    "payload": {
      "id": "add_01hv8gq3318ktkfengj2r75gfx",
      "city": "New York",
      "region": "NY",
      "status": "active",
      "created_at": "2024-04-12T06:42:58.785Z",
      "first_line": "4050 Jefferson Plaza, 41st Floor",
      "updated_at": "2024-04-12T06:42:58.785Z",
      "custom_data": null,
      "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "description": "Head Office",
      "import_meta": null,
      "postal_code": "10021",
      "second_line": null,
      "country_code": "US"
    },
    "last_run_at": null,
    "created_at": "2024-09-18T12:00:25.616392Z",
    "updated_at": "2024-09-18T12:00:25.616392Z"
  },
  "meta": {
    "request_id": "72351248-13bf-45be-befe-b3a5b5234588"
  }
}

Authorizations

Authorization

string

header

required

Requests are authenticated with API keys. Provide your API key as a Bearer token in the Authorization header.

API keys are assigned permissions, granting them access to entities and operations. Each endpoint may require one or more permissions, defined with the x-permissions extension. Values for include parameters may require specific permissions as defined in the x-enum-permissions extension. See all available permissions in the permission schema or documentation.

Get an API key and select the permissions you need from the Paddle dashboard under Paddle > Developer Tools > Authentication.

Body

application/json

Single event
Scenario

Single event simulations play a single event.

notification_setting_id

string

required

Paddle ID of the notification setting where this simulation is sent, prefixed with ntfset_.

Example:

"ntfset_01gt21c5pdx9q1e4mh1xrsjjn6"

name

string

required

Name of this simulation.

type

enum<string>

required

Single event sent for this simulation, in the format entity.event_type.

Available options:

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,

business.created,

business.imported,

business.updated,

customer.created,

customer.imported,

customer.updated,

discount.created,

discount.imported,

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

payload

object

Simulation payload. Pass a JSON object that matches the schema for an event type to simulate a custom payload. If omitted, Paddle populates with a demo example.

Response

Created

data

Single event · object

required

Single event simulations play a single event.

Single event
Scenario

Show child attributes

Updates

2026

2025

2024

Products

Prices

Transactions

Pricing preview

Adjustments

Customers

Addresses

Businesses

Payment methods

Customer portal sessions

Notification settings

Event types

Events

Notifications

Notification logs

Simulation types

Simulations

Simulation runs

Simulation run events

IP addresses

Discounts

Subscriptions

Reports

API Keys

Payouts

Create a simulation

Authorizations

Body

Response