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
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.
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 transactions, you can query by subscription ID, too. This lets you see all transactions for a subscription.
Return entities related to the specified subscription. Use a comma separated list to specify multiple subscription IDs.
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 and subscription events.
Match the transaction_id from transaction events with the transaction_id against the subscription.created event.
Transactions are flexible, so webhooks may occur in a different order depending on your customer journey.
Journey
- Customer opens checkout
- Customer enters their details and address information
- (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 with existing Paddle IDs. In this case, events for customer, address, and business entities may not occur.
Events
transaction.created | Paddle.js creates a transaction for the items on the checkout. Its status is draft while it's missing customer and address information. |
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 related to this customer. |
transaction.updated | Paddle updates the transaction with the new customer and address that was just created. |
transaction.ready | The transaction status changes to ready now that that the transaction has customer and address information. |
business.created | If a customer chooses to enter a tax/VAT number, Paddle creates a business. |
address.updated | When collecting business information, checkout collects a complete address. Paddle updates the address entity with the new information. |
transaction.updated | Paddle updates the transaction with the new business that was just created. Totals on the transaction may be updated to reflect changes in tax. Transaction items may have new IDs as a result. |
transaction.updated | When a customer adds a discount or makes changes to items or quantities, Paddle updates the transaction. |
transaction.paid | The transaction status changes to paid now that the customer has paid successfully. |
subscription.created | Paddle creates a subscription for the customer, address, and business against the transaction. |
subscription.trialing | If items on a subscription have a trial period, the subscription status is set to trialing. |
subscription.activated | After a trial period, or right away if there's no trial, the subscription status is set to active. |
transaction.updated | The transaction is updated with the ID of the new subscription and information about the successful payment. |
transaction.updated | An invoice number is assigned to the transaction. |
transaction.updated | invoice_id is added to the transaction. |
transaction.completed | The transaction status changes to completed as Paddle has finished processing it. |
As customers progress through your checkout, Paddle.js emits events for key actions and updates. 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.
