Handle provisioning and fulfillment

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:

1. 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.

2. 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.

3. 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:

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:

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:

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