Paddle Billing

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_id to the transaction entity.
  • For automatically-collected transactions, adding an invoice_number and invoice_id to 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 paid after payment is received successfully, but before transaction processing has completed.
  • Transactions are marked as completed after 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 paid transactions, though transactions won't typically be paid for 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.

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.

Learn more