Provision access to your app
Use webhooks to keep your app in sync with Paddle.
Provisioning is how you grant customers access to your app, as well as determining which features they should have access to.
For example:
- When customers first sign up, set them up with an account for your app.
- If customers add new modules, give them access to relevant features in your app.
- Where subscriptions are paused or canceled, limit or stop access to your app.
Get started
To handle provisioning, you should:
- Subscribe to webhooks for subscription events
- Verify signatures on receipt
- Build logic in your app to handle provisioning
Poll for changes using the event stream
Rather than using webhooks, you can use the
/eventsendpoint to get a stream of events and poll for changes.
How it works
Transactions
Transactions power subscription billing in Paddle. They tie together products, prices, and discounts with customers to calculate totals for subscriptions. They're the single source of truth for subscription billing, whether automatic (checkout) or manual (invoice).
Paddle creates a transaction automatically in the background when:
- Customers open checkout and enter customer and address information.
- You create a draft invoice.
As you work with a checkout or invoice, Paddle updates the related transaction. When a checkout completes or an invoice is issued, Paddle creates a related subscription. The subscription.created notification includes the related transaction_id, so you can match the new subscription to the transaction.
Renewals and changes to a subscription also create a related transaction. You can check:
next_transactionandrecurring_transaction_detailsagainst a subscription to see how future transactions looksubscription_idagainst a transaction to get a related subscription
When listing subscriptions, you can query by subscription ID, too. This lets you see all transactions for a subscription.
Paddle ID of the subscription that you'd like to get transactions for.
Payments
Though the terms "transaction" and "payment" are sometimes used interchangeably, they're distinct entities in Paddle:
- transactions calculate and captures revenue, ready for payment
- payments are attempts to collect for the amount against a transaction – both online and offline
Transactions may have more than one payment against them. For example, customers paying for larger value deals by invoice might make multiple payments, and automatically collected payments might fail.
Handle new subscriptions
To provision new subscriptions, listen for transaction events and subscription.created events.
Match the transaction_id from transaction events with the transaction_id against the subscription.created notification.
Webhooks may occur in a different order
Transactions are flexible, so webhooks may occur in a different order depending on your customer journey.
For example, you can pass an existing transaction ID to a checkout and send your customer a link to pay. When you do this, you won't get events to let you know that a customer, address, business, or transaction has been created.
Journey
- Customer opens checkout
- Customer enters their details and address information
- Paddle creates a transaction
- (optional) Customer enters business information
- Customer enters payment details
- Payment successful; transaction completed
- Paddle creates a subscription
You can speed up checkout by pre-filling customer, address, and business entities. In these cases, notifications for customer, address, and business entities may not occur.
Notifications
| Notification | Description |
|---|---|
customer.created | When a customer enters their email address, Paddle creates a customer if one can't be found that matches the email address. |
address.created | When a customer enters their country and ZIP/postal code, Paddle creates an address if one doesn't exist already. |
customer.updated | Addresses are linked to customers, so Paddle updates the customer with the new address. |
transaction.created | After Paddle has collected customer and address details, Paddle creates a transaction. |
business.created | If a customer enters a tax/VAT number, Paddle creates a business. |
customer.updated | Businesses are linked to customers, so Paddle updates the customer with the new business. |
transaction.updated | When a customers adds a business, adds a discount, or makes changes to items or quantities, Paddle updates the transaction. |
transaction.ready | When a transaction has all of the required fields against it, its status changes to ready. This may occur earlier in the process. |
transaction.payment_failed | Where a customer's payment fails, Paddle sends a transaction.payment_failed notification. |
transaction.completed | Where a customer's payment goes through successfully, a transaction changes to completed. |
subscription.created | At this point, Paddle creates a subscription. |
subscription.trialing | If a subscription has a trial period, its status is trialing and subscription.trialing occurs. |
subscription.activated | After a trial period, or right away if there's no trial period, a subscription changes to active and subscription.activated occurs. |
Build compelling checkout experiences with Paddle.js
As customers progress through your checkout, Paddle.js emits events for key events. Use these events to dynamically update your app or webpage when customers do things like enter their details, update items, add discounts, and make payments. See: Paddle.js events
