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:
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.
Get started
To handle provisioning, you should:
Subscribe to webhooks for subscription events
Create notification destinations for subscriptions, transactions, or other events in Paddle that you'd like 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 atransaction_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 is not 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.
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.
Related pages
- Handle provisioning and fulfillment
- How it works
- Core entities
- Get started
- Recommended events
- For a basic integration
- For a more comprehensive integration
- Recommended fields to store
- For a basic integration
- For a more comprehensive integration
- Recommended events and fields for lifecycle events
- Build a stateless integration
- Related pages