Documentation

Paddle Billing guide

Create a notification destination for transaction.completed, adjustment.created, and adjustment.updated. Paddle Classic is unsupported. Verify Paddle-Signature (ts=...;h1=...) as hex HMAC-SHA256 over timestamp:rawBody, using the unmodified endpoint secret. Multiple h1 signatures support rotation; the timestamp tolerance follows Paddle's five-second SDK default. Official signature verification.

Completed transactions use data.id, details.totals.grand_total as an integer string, currency_code, custom_data, customer_id, subscription_id, and product IDs from items/expanded line items. origin=subscription_recurring marks renewal. Earlier transaction.paid events are ignored. Completed transaction payload.

Only adjustments with action=refund and status=approved subtract revenue. Credits and pending_approval adjustments are ignored. The refund transaction is the adjustment id; its original is transaction_id; totals.total and currency_code describe its full or partial amount. Products and attribution come from the same-site/provider original payment. Adjustment payload.

Set customData: {ml_visitor_id, ml_session_id} using Paddle.Checkout.open, data-custom-data, or server API custom_data. Metadata propagates through subscriptions to later transactions. Hosted checkout does not document arbitrary metadata URL fields; app_user_id has RevenueCat semantics and is not repurposed. Custom data, hosted checkout parameters.

No live notification destination or refund approval workflow was exercised.