Get essential fields for provisioning in transaction.completed events
Completed transaction processing is more granular, with a new paid status for transactions and a new transaction.paid event. transaction.completed now has all the details you need for provisioning.
What's new?
We added a new paid value for transaction.status. It occurs when a transaction is paid, but hasn't yet been fully processed by Paddle.
Status of this transaction.
As part of this, we added a corresponding transaction.paid event.
How it works
When a transaction is paid successfully, it starts completed transaction processing in Paddle. This involves:
- Logging details of the successful payment against
transaction.payments[]. - Adding information about fees, earnings, and totals for payouts to the transaction entity.
- For automatically-collected transactions, creating a subscription for any recurring items and adding the related
subscription_idto the transaction entity. - For automatically-collected transactions, adding an
invoice_numberandinvoice_idto the transaction entity.
For performance and reliability reasons, these processes happen asynchronously. This means that they don't occur at the same time that the transaction status is updated to completed, they usually happen immediately after.
The new paid status for transactions makes this process more granular:
- Transactions are marked as
paidafter payment is received successfully, but before transaction processing has completed. - Transactions are marked as
completedafter transaction processing has completed.
When a transaction has the status of completed, you can be sure it won't be updated further as part of completed transaction processing.
You can filter to see
paidtransactions, though transactions won't typically bepaidfor long — completed transaction processing usually takes less than a second.
What about events?
The biggest impact is that transaction.completed events now include everything you need for provisioning access to your app.
Previously, transaction.completed events occurred immediately after the transaction status changed to completed. This meant that the payload didn't include subscription_id and invoice_number, since these fields are updated afterward as part of processing.
Here's a summary of events that occur when a transaction is completed. On the left, is the order before; on the right is the order now we've introduced transaction.paid.
Payment received
For automatically-collected transactions, customer completes checkout. For manually-collected transactions, payment received for the invoice.
transaction.completedThe transaction status changes to
completed.transaction.paidThe transaction status changes to
paid.Processing starts
Paddle starts completed transaction processing, updating the transaction with information as it's processed. For automatically-collected transactions, Paddle adds the
subscription_idfor the newly created subscription for the recurring items on the transaction.transaction.updatedThis may occur multiple times as Paddle adds information about related entities to the transaction.
transaction.updatedThis may occur multiple times as Paddle adds information about related entities to the transaction.
Processing completed
Paddle has finished completed transaction processing. The transaction won't be updated further as part of completed processing.
transaction.completedThe transaction status changes to
completed.
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. transaction.updated events still occur when Paddle processes transactions after payment, so you can still use them to listen for subscription_id, invoice_number, and other fields.
You can create or update a notification destination to subscribe to events for transaction.paid.
