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

# Use your data in single event simulation payloads

Pass Paddle IDs as part of the payload for single simulations to use data for those entities as part of your simulation. Plus, you can supply partial payloads.

---

## What's new?

We've updated webhook simulator so that now you can use your own data when customizing the payload for a single event simulation.

As part of this change, you can also supply a partial payload to override just the properties you specified.

## How it works

You can use [webhook simulator](https://developer.paddle.com/webhooks/test-webhooks.md) to send test webhooks for single events or predefined scenarios as part of testing and integration.

When working with a single event scenario, you can include a `payload` to send specific data as part of your request. Paddle saves your simulated data, so you can use it in the future.

With this update, if you pass [Paddle IDs](https://developer.paddle.com/api-reference/about/paddle-ids.md) that match Paddle IDs for entities on your system as part of the `payload`, then Paddle uses that data as part of your simulation. For example, you can pass the Paddle ID for [a transaction](https://developer.paddle.com/api-reference/transactions/overview.md) to run a simulation that includes the items, customer information, and other data on that transaction.

As part of this change, you can now supply partial payloads. When fields are omitted, and the included fields aren't Paddle IDs for existing entities, Paddle prefills data using sample data.

## Examples

#### Customize simulation payload

[Update a simulation](https://developer.paddle.com/api-reference/simulations/update-simulation.md) to include a custom payload for a single event simulation. Pass the Paddle ID for an entity in your system as a top-level ID.

You can also include a custom payload when [creating a simulation](https://developer.paddle.com/api-reference/simulations/update-simulation.md).

This example updates a `transaction.past_due` single event simulation to use data from an existing transaction.

{% api-example method="PATCH" path="/simulations/{simulation_id}" %}

```json {% title="Request" %}
{
  "type": "transaction.past_due",
  "payload": {
    "id": "txn_01jfhs9jys8caarfd334s3kbrx"
  }
}
```

{% /api-example %}

#### Run the simulation

[Create a run for a simulation](https://developer.paddle.com/api-reference/simulation-runs/create-simulation-run.md) to send the event or events that are part of it.

{% api-example method="POST" path="/simulations/{simulation_id}/runs" %}

```json {% title="Response" %}
{
  "data": {
    "id": "ntfsimrun_01jfhwqrzk5w9577sgptjgze1r",
    "status": "pending",
    "type": "transaction.past_due",
    "created_at": "2024-12-20T11:20:10.484036Z",
    "updated_at": "2024-12-20T11:20:10.484036Z"
  },
  "meta": {
    "request_id": "46ad6dc7-03ec-49d5-af43-ad8b716ccc61"
  }
}
```

{% /api-example %}

#### List events for a simulation run

Paddle creates a simulation event for the event or events that are part of a simulation run. [List events for a simulation run](https://developer.paddle.com/api-reference/simulation-events/list-simulation-events.md) to see the custom payload passed.

This example includes data from `txn_01jfhs9jys8caarfd334s3kbrx`, an existing transaction, rather than sample data.

{% api-example method="GET" path="/simulations/{simulation_id}/runs/{simulation_run_id}/events" %}

```json {% title="Response" collapse=true %}
{
  "data": [
    {
      "id": "ntfsimevt_01jfhwqs6xydvf6yjwtjv3a31d",
      "status": "success",
      "event_type": "transaction.past_due",
      "payload": {
        "id": "txn_01jfhs9jys8caarfd334s3kbrx",
        "items": [
          {
            "price": {
              "id": "pri_01gsz91wy9k1yn7kx82aafwvea",
              "name": "Annual (per seat)",
              "type": "standard",
              "status": "active",
              "quantity": {
                "maximum": 100,
                "minimum": 1
              },
              "tax_mode": "account_setting",
              "created_at": "2023-02-23T13:57:54.249913Z",
              "product_id": "pro_01gsz4vmqbjk3x4vvtafffd540",
              "unit_price": {
                "amount": "50000",
                "currency_code": "USD"
              },
              "updated_at": "2024-04-05T14:32:00.471447Z",
              "custom_data": null,
              "description": "Annual",
              "import_meta": null,
              "trial_period": null,
              "billing_cycle": {
                "interval": "year",
                "frequency": 1
              },
              "unit_price_overrides": []
            },
            "quantity": 100,
            "proration": null
          }
        ],
        "origin": "api",
        "status": "billed",
        "details": {
          "totals": {
            "fee": null,
            "tax": "399375",
            "total": "4899375",
            "credit": "0",
            "balance": "4899375",
            "discount": "500000",
            "earnings": null,
            "subtotal": "5000000",
            "grand_total": "4899375",
            "currency_code": "USD",
            "credit_to_balance": "0"
          },
          "line_items": [
            {
              "id": "txnitm_01jfhs9kadem5hv4t6ej3f7h30",
              "totals": {
                "tax": "399375",
                "total": "4899375",
                "discount": "500000",
                "subtotal": "5000000"
              },
              "product": {
                "id": "pro_01gsz4vmqbjk3x4vvtafffd540",
                "name": "AeroEdit Enterprise",
                "type": "standard",
                "status": "active",
                "image_url": "https://paddle.s3.amazonaws.com/user/165798/Ws808ziTS76a6YbnMkiK_enterprise.png",
                "created_at": "2023-02-23T12:44:34.923Z",
                "updated_at": "2024-04-05T15:58:28.309Z",
                "custom_data": {
                  "features": {
                    "sso": true,
                    "route_planning": true,
                    "payment_by_invoice": true,
                    "aircraft_performance": true,
                    "compliance_monitoring": true,
                    "flight_log_management": true
                  },
                  "suggested_addons": [
                    "pro_01h1vjes1y163xfj1rh1tkfb65",
                    "pro_01gsz97mq9pa4fkyy0wqenepkz"
                  ],
                  "upgrade_description": "Ready to reach new heights? Upgrade to enterprise to unlock single sign-on, payment by invoice, and dedicated account management."
                },
                "description": "The ultimate solution for organizations, featuring all Pro capabilities plus multi-user support, advanced data storage capabilities, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.",
                "import_meta": null,
                "tax_category": "standard"
              },
              "price_id": "pri_01gsz91wy9k1yn7kx82aafwvea",
              "quantity": 100,
              "tax_rate": "0.08875",
              "proration": null,
              "unit_totals": {
                "tax": "3994",
                "total": "48994",
                "discount": "5000",
                "subtotal": "50000"
              }
            },
            {
              "id": "txnitm_01hv8xbv0wdggp4a933cx2m9qc",
              "totals": {
                "tax": "887",
                "total": "10887",
                "discount": "0",
                "subtotal": "10000"
              },
              "product": {
                "id": "pro_01h1vjes1y163xfj1rh1tkfb65",
                "name": "Analytics addon",
                "type": "standard",
                "status": "active",
                "image_url": "https://paddle.s3.amazonaws.com/user/165798/97dRpA6SXzcE6ekK9CAr_analytics.png",
                "created_at": "2023-06-01T13:30:50.302Z",
                "updated_at": "2024-04-05T15:47:17.163Z",
                "custom_data": null,
                "description": "Unlock advanced insights into your flight data with enhanced analytics and reporting features. Includes customizable reporting templates and trend analysis across flights.",
                "import_meta": null,
                "tax_category": "standard"
              },
              "price_id": "pri_01h1vjfevh5etwq3rb416a23h2",
              "quantity": 1,
              "tax_rate": "0.08875",
              "proration": {
                "rate": "1",
                "billing_period": {
                  "ends_at": "2024-06-12T10:18:47.635628Z",
                  "starts_at": "2024-05-12T10:18:47.635628Z"
                }
              },
              "unit_totals": {
                "tax": "887",
                "total": "10887",
                "discount": "0",
                "subtotal": "10000"
              }
            }
          ],
          "payout_totals": null,
          "tax_rates_used": [
            {
              "totals": {
                "tax": "399375",
                "total": "4899375",
                "discount": "500000",
                "subtotal": "5000000"
              },
              "tax_rate": "0.08875"
            }
          ],
          "adjusted_totals": {
            "fee": null,
            "tax": "399375",
            "total": "4899375",
            "earnings": null,
            "subtotal": "4500000",
            "grand_total": "4899375",
            "currency_code": "USD"
          },
          "adjusted_payout_totals": null
        },
        "checkout": {
          "url": "https://michael-paddle-billing-aeroedit-test.vercel.app/?_ptxn=txn_01jfhs9jys8caarfd334s3kbrx"
        },
        "payments": [
          {
            "amount": "43549",
            "status": "error",
            "created_at": "2024-04-12T10:24:01.692772Z",
            "error_code": "authentication_failed",
            "captured_at": null,
            "method_details": {
              "card": {
                "type": "visa",
                "last4": "3184",
                "expiry_year": 2025,
                "expiry_month": 1,
                "cardholder_name": "Michael McGovern"
              },
              "type": "card"
            },
            "payment_method_id": "paymtd_01hv8x1tpjfnttxddw73xnqx6s",
            "payment_attempt_id": "ff8123f6-9cfc-4f04-9984-75e4ad04b169",
            "stored_payment_method_id": "281ff2ca-8550-42b9-bf39-15948e7de62d"
          }
        ],
        "billed_at": "2024-12-20T10:19:59.833535Z",
        "address_id": "add_01jfhf4p337sw2ffcc4b5msk2c",
        "created_at": "2024-12-20T10:20:00.23312Z",
        "invoice_id": "inv_01jfhs9m4qbca9n05jyjv0gajt",
        "updated_at": "2024-12-20T10:20:05.467429Z",
        "business_id": "biz_01j1ysxgk6pb33c2d5b980grjb",
        "custom_data": null,
        "customer_id": "ctm_01hrffh7gvp29kc7xahm8wddwa",
        "discount_id": "dsc_01gtgraak4chyhnp47rrdv89ad",
        "receipt_data": null,
        "currency_code": "USD",
        "billing_period": {
          "ends_at": "2025-12-20T10:20:00.917Z",
          "starts_at": "2024-12-20T10:20:00.917Z"
        },
        "invoice_number": "325-13504",
        "billing_details": {
          "payment_terms": {
            "interval": "day",
            "frequency": 14
          },
          "enable_checkout": true,
          "purchase_order_number": "PO-1234",
          "additional_information": ""
        },
        "collection_mode": "manual",
        "subscription_id": "sub_01jfhs9m0xpwfzwxct31a5s1tk"
      },
      "request": {
        "body": "{\"event_id\":\"ntfsimevt_01jfhwqs6xydvf6yjwtjv3a31d\",\"event_type\":\"transaction.past_due\",\"occurred_at\":\"2024-12-20T11:20:10.717394Z\",\"notification_id\":\"ntfsimntf_01jfhwqsdeyz694bcpghrp0g4e\",\"data\":{\"id\":\"txn_01jfhs9jys8caarfd334s3kbrx\",\"items\":[{\"price\":{\"id\":\"pri_01gsz91wy9k1yn7kx82aafwvea\",\"name\":\"Annual (per seat)\",\"type\":\"standard\",\"status\":\"active\",\"quantity\":{\"maximum\":100,\"minimum\":1},\"tax_mode\":\"account_setting\",\"created_at\":\"2023-02-23T13:57:54.249913Z\",\"product_id\":\"pro_01gsz4vmqbjk3x4vvtafffd540\",\"unit_price\":{\"amount\":\"50000\",\"currency_code\":\"USD\"},\"updated_at\":\"2024-04-05T14:32:00.471447Z\",\"custom_data\":null,\"description\":\"Annual\",\"import_meta\":null,\"trial_period\":null,\"billing_cycle\":{\"interval\":\"year\",\"frequency\":1},\"unit_price_overrides\":[]},\"quantity\":100,\"proration\":null},{\"price\":{\"id\":\"pri_01h1vjfevh5etwq3rb416a23h2\",\"name\":\"Monthly (recurring addon)\",\"type\":\"standard\",\"status\":\"active\",\"quantity\":{\"maximum\":100,\"minimum\":1},\"tax_mode\":\"account_setting\",\"created_at\":\"2023-06-01T13:31:12.625056Z\",\"product_id\":\"pro_01h1vjes1y163xfj1rh1tkfb65\",\"unit_price\":{\"amount\":\"10000\",\"currency_code\":\"USD\"},\"updated_at\":\"2024-04-09T07:23:00.907834Z\",\"custom_data\":null,\"description\":\"Monthly\",\"import_meta\":null,\"trial_period\":null,\"billing_cycle\":{\"interval\":\"month\",\"frequency\":1},\"unit_price_overrides\":[]},\"quantity\":1,\"proration\":{\"rate\":\"1\",\"billing_period\":{\"ends_at\":\"2024-06-12T10:18:47.635628Z\",\"starts_at\":\"2024-05-12T10:18:47.635628Z\"}}}],\"origin\":\"api\",\"status\":\"billed\",\"details\":{\"totals\":{\"fee\":null,\"tax\":\"399375\",\"total\":\"4899375\",\"credit\":\"0\",\"balance\":\"4899375\",\"discount\":\"500000\",\"earnings\":null,\"subtotal\":\"5000000\",\"grand_total\":\"4899375\",\"currency_code\":\"USD\",\"credit_to_balance\":\"0\"},\"line_items\":[{\"id\":\"txnitm_01jfhs9kadem5hv4t6ej3f7h30\",\"totals\":{\"tax\":\"399375\",\"total\":\"4899375\",\"discount\":\"500000\",\"subtotal\":\"5000000\"},\"product\":{\"id\":\"pro_01gsz4vmqbjk3x4vvtafffd540\",\"name\":\"AeroEdit Enterprise\",\"type\":\"standard\",\"status\":\"active\",\"image_url\":\"https://paddle.s3.amazonaws.com/user/165798/Ws808ziTS76a6YbnMkiK_enterprise.png\",\"created_at\":\"2023-02-23T12:44:34.923Z\",\"updated_at\":\"2024-04-05T15:58:28.309Z\",\"custom_data\":{\"features\":{\"sso\":true,\"route_planning\":true,\"payment_by_invoice\":true,\"aircraft_performance\":true,\"compliance_monitoring\":true,\"flight_log_management\":true},\"suggested_addons\":[\"pro_01h1vjes1y163xfj1rh1tkfb65\",\"pro_01gsz97mq9pa4fkyy0wqenepkz\"],\"upgrade_description\":\"Ready to reach new heights? Upgrade to enterprise to unlock single sign-on, payment by invoice, and dedicated account management.\"},\"description\":\"The ultimate solution for organizations, featuring all Pro capabilities plus multi-user support, advanced data storage capabilities, plus personalized onboarding, dedicated account management, and the ability to pay via invoice.\",\"import_meta\":null,\"tax_category\":\"standard\"},\"price_id\":\"pri_01gsz91wy9k1yn7kx82aafwvea\",\"quantity\":100,\"tax_rate\":\"0.08875\",\"proration\":null,\"unit_totals\":{\"tax\":\"3994\",\"total\":\"48994\",\"discount\":\"5000\",\"subtotal\":\"50000\"}},\"unit_totals\":{\"tax\":\"887\",\"total\":\"10887\",\"discount\":\"0\",\"subtotal\":\"10000\"}}],\"payout_totals\":null,\"tax_rates_used\":[{\"totals\":{\"tax\":\"399375\",\"total\":\"4899375\",\"discount\":\"500000\",\"subtotal\":\"5000000\"},\"tax_rate\":\"0.08875\"}],\"adjusted_totals\":{\"fee\":null,\"tax\":\"399375\",\"total\":\"4899375\",\"earnings\":null,\"subtotal\":\"4500000\",\"grand_total\":\"4899375\",\"currency_code\":\"USD\"},\"adjusted_payout_totals\":null},\"checkout\":{\"url\":\"https://michael-paddle-billing-aeroedit-test.vercel.app/?_ptxn=txn_01jfhs9jys8caarfd334s3kbrx\"},\"payments\":[{\"amount\":\"43549\",\"status\":\"error\",\"created_at\":\"2024-04-12T10:24:01.692772Z\",\"error_code\":\"authentication_failed\",\"captured_at\":null,\"method_details\":{\"card\":{\"type\":\"visa\",\"last4\":\"3184\",\"expiry_year\":2025,\"expiry_month\":1,\"cardholder_name\":\"Michael McGovern\"},\"type\":\"card\"},\"payment_method_id\":\"paymtd_01hv8x1tpjfnttxddw73xnqx6s\",\"payment_attempt_id\":\"ff8123f6-9cfc-4f04-9984-75e4ad04b169\",\"stored_payment_method_id\":\"281ff2ca-8550-42b9-bf39-15948e7de62d\"}],\"billed_at\":\"2024-12-20T10:19:59.833535Z\",\"address_id\":\"add_01jfhf4p337sw2ffcc4b5msk2c\",\"created_at\":\"2024-12-20T10:20:00.23312Z\",\"invoice_id\":\"inv_01jfhs9m4qbca9n05jyjv0gajt\",\"updated_at\":\"2024-12-20T10:20:05.467429Z\",\"business_id\":\"biz_01j1ysxgk6pb33c2d5b980grjb\",\"custom_data\":null,\"customer_id\":\"ctm_01hrffh7gvp29kc7xahm8wddwa\",\"discount_id\":\"dsc_01gtgraak4chyhnp47rrdv89ad\",\"receipt_data\":null,\"currency_code\":\"USD\",\"billing_period\":{\"ends_at\":\"2025-12-20T10:20:00.917Z\",\"starts_at\":\"2024-12-20T10:20:00.917Z\"},\"invoice_number\":\"325-13504\",\"billing_details\":{\"payment_terms\":{\"interval\":\"day\",\"frequency\":14},\"enable_checkout\":true,\"purchase_order_number\":\"PO-1234\",\"additional_information\":\"\"},\"collection_mode\":\"manual\",\"subscription_id\":\"sub_01jfhs9m0xpwfzwxct31a5s1tk\"}}"
      },
      "response": {
        "body": "{\"status\":\"SUCCESS\",\"message\":\"Request handled by Hookdeck. Check your dashboard to inspect the request: https://dashboard.hookdeck.com/requests/req_kbeADA78ys51nvjF8Zci\",\"request_id\":\"req_kbeADA78ys51nvjF8Zci\"}",
        "status_code": 200
      },
      "created_at": "2024-12-20T11:20:10.717394Z",
      "updated_at": "2024-12-20T11:20:11.189163Z"
    }
  ],
  "meta": {
    "pagination": {
      "per_page": 50,
      "estimated_total": 3,
      "next": "https://api.paddle.com/simulations/ntfsim_01jfhrhbssv0msbkjpedt6r60j/runs/ntfsimrun_01jfhwqrzk5w9577sgptjgze1r/events?after=ntfsimevt_01jfhwqs6xydvf6yjwtjv3a31d",
      "has_more": false
    },
    "request_id": "d22300a2-e3ce-4879-8752-6d8feffd4136"
  }
}
```

{% /api-example %}

## Next steps

This change is available in version `1` of the Paddle API.

It's a non-breaking change, meaning it doesn't impact existing integrations.

Customize a payload when [creating or updating a simulation](https://developer.paddle.com/webhooks/test-webhooks.md) to use your own data.
## Summary of changes

| Name | Type | Change | Entity | Description |
| --- | --- | --- | --- | --- |
| `payload` | Field | updated | Simulation | Accepts partial payloads; Paddle IDs are resolved to entity data. |