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

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:

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 transactions, 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 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

  1. Customer opens checkout
  2. Customer enters their details and address information
  3. (optional) Customer enters business information
  4. Customer enters payment details
  5. Payment successful; transaction completed
  6. 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.createdPaddle.js creates a transaction for the items on the checkout. Its status is draft while it's missing customer and address information.
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 related to this customer.
transaction.updatedPaddle updates the transaction with the new customer and address that was just created.
transaction.readyThe transaction status changes to ready now that that the transaction has customer and address information.
business.createdIf a customer chooses to enter a tax/VAT number, Paddle creates a business.
address.updatedWhen collecting business information, checkout collects a complete address. Paddle updates the address entity with the new information.
transaction.updatedPaddle 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.updatedWhen a customer adds a discount or makes changes to items or quantities, Paddle updates the transaction.
transaction.paidThe transaction status changes to paid now that the customer has paid successfully.
subscription.createdPaddle creates a subscription for the customer, address, and business against the transaction.
subscription.trialingIf items on a subscription have a trial period, the subscription status is set to trialing.
subscription.activatedAfter a trial period, or right away if there's no trial, the subscription status is set to active.
transaction.updatedThe transaction is updated with the ID of the new subscription and information about the successful payment.
transaction.updatedAn invoice number is assigned to the transaction.
transaction.updatedinvoice_id is added to the transaction.
transaction.completedThe 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.

Related pages