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.
- 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.
To handle provisioning, you should:
- Subscribe to webhooks for subscription events
- Verify signatures on receipt
- Build logic in your app to handle provisioning
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:
recurring_transaction_detailsagainst a subscription to see how future transactions look
subscription_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.
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.
To provision new subscriptions, listen for
transaction events and
transaction events with the
transaction_id against the
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.
- 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.
|When a customer enters their email address, Paddle creates a customer if one can't be found that matches the email address.|
|When a customer enters their country and ZIP/postal code, Paddle creates an address if one doesn't exist already.|
|Addresses are linked to customers, so Paddle updates the customer with the new address.|
|After Paddle has collected customer and address details, Paddle creates a transaction.|
|If a customer enters a tax/VAT number, Paddle creates a business.|
|Businesses are linked to customers, so Paddle updates the customer with the new business.|
|When a customers adds a business, adds a discount, or makes changes to items or quantities, Paddle updates the transaction.|
|When a transaction has all of the required fields against it, its status changes to |
|Where a customer's payment fails, Paddle sends a |
|Where a customer's payment goes through successfully, a transaction changes to |
|At this point, Paddle creates a subscription.|
|If a subscription has a trial period, its status is |
|After a trial period, or right away if there's no trial period, a subscription changes to |
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