Transactions
transaction.ready
Occurs when a transaction is ready to be billed. Its status field changes to ready.
Transactions are ready when they have all the required fields against them to be transitioned to billed or completed. This includes items, customer_id, and address_id. Paddle automatically marks transactions as ready when these fields are present.
When working with manually-collected transactions (invoices), transaction.updated may occur immediately after to add invoice_id and adjusted_totals.
postWebhooktransaction.ready
Headers
paddle_signaturestring required
Signature for this request. Use to verify that webhooks come from Paddle.
Payload
Example payload
{
"event_id": "evt_01gks14ge726w50ch2tmaw2a1x",
"occurred_at": "2024-10-12T07:20:50.52Z",
"notification_id": "ntf_01ghbkd0frb9k95cnhwd1bxpvk",
"data": {
"id": "txn_01h04vsbhqc62t8hmd4z3b578c",
"customer_id": "ctm_01grnn4zta5a1mf02jjze7y2ys",
"address_id": "add_01gm302t81w94gyjpjpqypkzkf",
"business_id": "biz_01grrebrzaee2qj2fqqhmcyzaj",
"custom_data": {
"customer_reference_id": "abcd1234"
},
"subscription_id": "sub_01h04vsc0qhwtsbsxh3422wjs4",
"invoice_id": "inv_01ghbk4xjn4qdsmstcwzgcgg35",
"invoice_number": "123-45678",
"discount_id": "dsc_01gv5kpg05xp104ek2fmgjwttf",
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
},
"items": [
{
"price": {
"id": "pri_01gsz8z1q1n00f12qt82y31smh",
"product_id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
"quantity": {
"minimum": 1,
"maximum": 100
},
"custom_data": {
"customer_reference_id": "abcd1234"
},
"import_meta": {
"external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
"imported_from": "paddle_classic"
},
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z"
},
"proration": {
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
}
}
}
],
"details": {
"tax_rates_used": [
{
"tax_rate": "0.2",
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
}
}
],
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500",
"credit": "0",
"credit_to_balance": "0",
"balance": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"earnings": "15675"
},
"adjusted_totals": {
"subtotal": "15000",
"tax": "1500",
"total": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"retained_fee": "300",
"earnings": "15675"
},
"payout_totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500",
"credit": "0",
"credit_to_balance": "0",
"balance": "16500",
"grand_total": "16500",
"grand_total_tax": "83",
"fee": "825",
"earnings": "15675",
"exchange_rate": "1.0513135",
"fee_rate": "0.05"
},
"adjusted_payout_totals": {
"subtotal": "15000",
"tax": "1500",
"total": "16500",
"fee": "825",
"retained_fee": "300",
"chargeback_fee": {
"amount": "1680",
"original": {
"amount": "1500",
"currency_code": "USD"
}
},
"earnings": "15675",
"exchange_rate": "1.0513135"
},
"line_items": [
{
"price_id": "pri_01gsz8z1q1n00f12qt82y31smh",
"proration": {
"billing_period": {
"starts_at": "2024-10-12T07:20:50.52Z",
"ends_at": "2024-10-12T07:20:50.52Z"
}
},
"tax_rate": "0.2",
"unit_totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
},
"totals": {
"subtotal": "15000",
"discount": "0",
"tax": "1500",
"total": "16500"
},
"product": {
"id": "pro_01gsz97mq9pa4fkyy0wqenepkz",
"custom_data": {
"customer_reference_id": "abcd1234"
},
"import_meta": {
"external_id": "9b95b0b8-e10f-441a-862e-1936a6d818ab",
"imported_from": "paddle_classic"
},
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z"
},
"id": "txnitm_01gm302t81w94gyjpjpqypkzkf"
}
]
},
"payments": [
{
"payment_attempt_id": "497f776b-851d-4ebf-89ab-8ba0f75d2d6a",
"stored_payment_method_id": "7636e781-3969-49f4-9c77-8226232e28a6",
"payment_method_id": "paymtd_01hkm9xwqpbbpr1ksmvg3sx3v1",
"amount": "1050",
"method_details": {
"south_korea_local_card": {
"last4": "4242"
},
"card": {
"last4": "4242",
"expiry_month": 12,
"expiry_year": 2028
},
"paypal": {
"email": "john.doe@example.com"
}
},
"created_at": "2024-10-12T07:20:50.52Z",
"captured_at": "2024-10-12T07:20:50.52Z"
}
],
"created_at": "2024-10-12T07:20:50.52Z",
"updated_at": "2024-10-13T07:20:50.52Z",
"billed_at": "2024-10-12T07:20:50.52Z",
"revised_at": "2024-10-12T07:20:50.52Z"
}
}Response
Respond with an HTTP 200 status code within 5 seconds to let Paddle know that you successfully received the message.
If your server sends another kind of status code or doesn't respond, Paddle automatically retries using an exponential backoff schedule.
Changes
Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.