Contents
Appendix A. How PaddleSubs Handles Each Paddle Event
What each webhook Paddle sends changes on your site.
Every webhook is saved in the queue and processed by the
PaddleSubs - Process webhooks task, in the order its events happened.
Events not listed here are saved and ignored. Paddle can deliver an entity's events out of order; an event
older than one already processed for the same transaction, subscription or customer is skipped, so it can't
undo newer information. A transaction.completed is the exception: it is always processed,
even when Paddle retried it after later updates, since skipping it would lose the purchase.
Transactions
transaction.created-
Records the transaction, and connects its customer to a Joomla account if Paddle already names one. Paddle sends it as soon as a checkout opens, often before there is a customer, so it creates no access.
transaction.updated,transaction.canceled-
Record the transaction's new status and details, and connect its customer. Paddle only cancels transactions that were never paid, such as an invoice you withdrew, so a cancel takes no access away; refunds arrive as adjustments.
transaction.completed-
The payment went through. For each product bought, PaddleSubs creates an Access Subscription (and, for a licensed product, finds or creates the license), adds the groups if it starts now, and sends the purchase email. What the payment buys depends on its origin:
Origin What it buys web,apiA purchase: one period of the price, stacked after current access for products that stack. subscription_recurringA renewal: the next billing period. subscription_update,subscription_chargeA change to a Paddle subscription: access up to the end of the billing period the change was charged for, only where the customer's access doesn't already reach that far. Seats don't change here. A line that isn't prorated is a full charge and buys a period like a purchase, and a line with a negative quantity, the credit for an item the change removed, buys nothing. subscription_payment_method_changeNothing: it only checks a new card. A line that can't be handled safely is quarantined and logged instead: no Joomla user, a product or price the site doesn't know, or a change whose billing period is unknown. A custom price the site knows is granted like any other; one it doesn't know, such as a price Paddle made for an invoice created in its dashboard, is held until it is set up from the Needs Attention page.
transaction.ready,.billed,.paid,.past_due,.payment_failed,.revised-
Recorded; no action. A failed renewal leaves access to end when the last paid period does.