Get essential fields for provisioning in transaction.completed events

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 string

Status of this transaction.

paid

Transaction is fully paid, but has not yet been processed internally.

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.

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.completed
  The transaction status changes to completed.
- transaction.paid
  The 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_id for the newly created subscription for the recurring items on the transaction.
- transaction.updated
  This may occur multiple times as Paddle adds information about related entities to the transaction.
- transaction.updated
  This 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.completed
  The 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.

Entity	Field	Change	Type
Transaction.status	`paid`	+ Added	Enum value
Transaction is paid but processing isn't yet complete.
Transactions	`transaction.paid`	+ Added	Webhook
Occurs when a transaction is paid but processing isn't yet complete.