Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing
Search

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:

  1. Subscribe to webhooks for subscription events
  2. Verify signatures on receipt
  3. Build logic in your app to handle provisioning

Poll for changes using the event stream

Rather than using webhooks, you can use the /events endpoint 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_transaction and recurring_transaction_details against a subscription to see how future transactions look
  • subscription_id against 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.

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

  1. Customer opens checkout
  2. Customer enters their details and address information
  3. Paddle creates a transaction
  4. (optional) Customer enters business information
  5. Customer enters payment details
  6. Payment successful; transaction completed
  7. 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

NotificationDescription
customer.createdWhen a customer enters their email address, Paddle creates a customer if one can't be found that matches the email address.
address.createdWhen a customer enters their country and ZIP/postal code, Paddle creates an address if one doesn't exist already.
customer.updatedAddresses are linked to customers, so Paddle updates the customer with the new address.
transaction.createdAfter Paddle has collected customer and address details, Paddle creates a transaction.
business.createdIf a customer enters a tax/VAT number, Paddle creates a business.
customer.updatedBusinesses are linked to customers, so Paddle updates the customer with the new business.
transaction.updatedWhen a customers adds a business, adds a discount, or makes changes to items or quantities, Paddle updates the transaction.
transaction.readyWhen a transaction has all of the required fields against it, its status changes to ready. This may occur earlier in the process.
transaction.payment_failedWhere a customer's payment fails, Paddle sends a transaction.payment_failed notification.
transaction.completedWhere a customer's payment goes through successfully, a transaction changes to completed.
subscription.createdAt this point, Paddle creates a subscription.
subscription.trialingIf a subscription has a trial period, its status is trialing and subscription.trialing occurs.
subscription.activatedAfter 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

Related pages