Use your data in single event simulation 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 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 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 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 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.

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

PATCH /simulations/{simulation_id}

Request

{
  "type": "transaction.past_due",
  "payload": {
    "id": "txn_01jfhs9jys8caarfd334s3kbrx"
  }
}

Run the simulation

Create a run for a simulation to send the event or events that are part of it.

POST /simulations/{simulation_id}/runs

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"
  }
}

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 to see the custom payload passed.

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

GET /simulations/{simulation_id}/runs/{simulation_run_id}/events

Response

{
  "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"
  }
}

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 to use your own data.

Entity	Field	Change	Type
Simulation	`payload`	~ Updated	Field
Accepts partial payloads; Paddle IDs are resolved to entity data.