Transactions
transaction.billed
Occurs when a transaction is billed. Its status field changes to billed and billed_at is populated.
Marking a transaction as billed is typically used when working with manually-collected transactions to issue an invoice. It's not typically part of checkout workflows, where collection mode is automatic.
Transactions are marked as billed when:
- You update its status to billed using the API.
- You send an invoice (a manually-collected transaction) using the Paddle dashboard.
Billed transactions get an invoice number. They're considered legal records, so they can't be deleted or updated, only canceled.
transaction.updated events occur immediately after to add:
- invoice_number, and invoice_id if not already present.
- If manually-collected, the newly created subscription_id for any recurring items.
postWebhooktransaction.billed
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.