Handle provisioning and fulfillment

Use webhooks to keep your app in sync with Paddle and determine what access customers have.

Provisioning is how you grant customers access to your app, as well as determining which features they should have access to. It's sometimes called fulfillment. For example:

When customers sign up, set them up with an account for your app.
If customers add or remove products for additional modules, give them access to relevant features in your app.
Where subscriptions are paused or canceled, limit or stop access to your app.

You can use webhooks in Paddle to notify your app when an event happens that means you need to change customer access.

How it works

When integrating with Paddle, you should store some Paddle data in your own database to keep your app in sync with changes that happen to customer subscriptions. For example, you should store the id of a related subscription in your database so you can work with that subscription using the Paddle API in the future.

While your app might initiate some changes, like sending a call to the Paddle API to add items when a customer upgrades, some changes can happen asynchronously at any time. For example, a subscription may become past due when there's a problem with a customer payment method.

You can subscribe to webhooks to get notified when changes happen to a subscription to keep your app in sync with Paddle.

Core entities

Transactions and subscriptions are the core entities involved in the subscription lifecycle, and the most important events for provisioning. They're closely related, and subscription and transaction events often happen together. For example:

Transactions are how subscriptions are created initially
Paddle automatically creates subscriptions when an automatically-collected transactions (checkouts) are completed, or when manually collected transactions (invoices) are issued.
Subscriptions create transactions to collect for payment
Paddle automatically creates transactions for subscription lifecycle events, like renewals, upgrades or downgrades, or when one-time charges are billed to a subscription.

Overview

To handle provisioning, you should:

Subscribe to webhooks for subscription events
Create notification destinations for subscriptions, transactions, or other events in Paddle that you want to use to keep your app in sync with Paddle.
Check received webhooks for changes and update fields in your database
When you receive webhooks from Paddle, check the returned data object for changes to fields that you're keeping in sync with your app. Update those fields in your database.
Handle changes and provision
Run workflows that you've built to handle subscription changes or change the level of access that a customer has to your app.

Recommended events

For a basic integration

At a minimum, we recommend that you subscribe to webhooks for:

`transaction.created`	Occurs when a transaction is created.
`subscription.created`	Occurs when a subscription is created.
`transaction.updated`	Occurs any time a change happens to a transaction, including status changes.
`subscription.updated`	Occurs any time a change happens to a subscription, including status changes.

Transactions created by subscriptions include a subscription_id field that you can use to match a transaction with a subscription. subscription.created includes a transaction_id field, too.

For a more comprehensive integration

subscription.updated and transaction.updated events occur for every change to a subscription or a transaction after they've been created.

However, you can subscribe to more granular events for all parts of the subscription lifecycle. For example, you can get notified when payment fails for a transaction, when a subscription moves out of trial, or when a subscription is canceled.

For specific recommendations on which events to subscribe to for subscription lifecycle events, check out our subscription lifecycle guides (below).

Recommended fields to store

For a basic integration

At a minimum, we recommend storing:

Description	Field name	Reason to store
Occurred at	`notification.occurred_at`	Used to check when an event occurred. The order of delivery for notifications isn't guaranteed, so you should check when an event occurred before making a change.
Subscription ID	`subscription.id`	Used to identify this subscription in webhook responses and work with this subscription using the API.
Subscription status	`subscription.status`	Used to limit or stop access when paused or canceled, or determine if a subscription is past due or trialing.
Subscription items	`subscription.items[].price.id`, `subscription.items[].quantity`	Used to change items on a subscription as part of an upgrade or downgrade workflow.
Subscription products	`subscription.items[].price.product_id`	Used to determine which features in your app a customer should have access to.
Collection mode	`subscription.collection_mode`	Used to determine whether a subscription bills automatically or whether Paddle sends an invoice for charges that customers must pay manually.
Scheduled change	`subscription.scheduled_change`	Used to determine whether a subscription is scheduled to pause or cancel. You can't change items on a subscription when there's a pending scheduled change.

For a more comprehensive integration

For the best user experience, you might like to build a subscription billing overview page. This should let customers see information about their subscription and make changes to it.

As well as the minimum recommended fields, we recommend storing:

Description	Field name	Reason to store
Next billing date	`subscription.next_billed_at`	Used to determine when a subscription renews if active, or when it's scheduled to resume if paused.
Billing period	`subscription.current_billing_period`	Used to determine when a billing period starts and ends. May be used as part of a workflow to change billing dates.
Last successful transaction totals	`transaction.details.totals`	Used to present information about a customer's last subscription payment.
Last successful payment information	`transaction.payments[].method_details`	For automatically-collected subscriptions, used to present information about the saved payment method and handle a payment method update workflow.
Payment method details	`subscription.billing_details`	For manually-collected subscriptions, used to present and update information that's included on invoices generated by Paddle.

For specific recommendations on which fields to store to for subscription lifecycle events, check out our subscription lifecycle guides (below).

Recommended events and fields for lifecycle events

These guides walk through what happens for each part of the subscription lifecycle, including which events occur, recommended workflow, and fields that you may like to store or update.

Subscription creation

Subscription renewal

Subscription past due

Subscription pause or resume

Subscription cancellation

Payment details update

Build a stateless integration

For performance and scalability, we strongly recommend storing information about subscriptions in a database and using webhooks keep that information up-to-date.

If you can't store information, you can make direct requests to the Paddle API to get information and work with subscriptions and transactions provided you have the ID for a customer. For example:

When listing transactions or subscriptions, you can use the customer_id query parameter to return entities related to a customer.
When listing transactions, you can use the subscription_id query parameter to return transactions related to a subscription.
When getting a transaction, you can include the related customer, address, business, and other entities to avoid making another call to the API.
When getting a subscription, you can include a preview of the next transaction and recurring transaction.

Webhooks

Paddle Checkout

Invoices