The subscription lifecycle

Introduction

Paddle handles all aspects of subscription management throughout a subscription's lifetime - notifying your platform (via webhooks) about key events so you can ensure that access to your product or service is always synchronized with the customer's subscription status:

In this guide, we aim to help you understand how Paddle manages the different phases in the lifecycle of a subscription.

Create subscription

A new subscription is created when a customer goes through your integrated Paddle checkout and completes one of the following actions:

• Pays for a new subscription successfully.
• Provides payment details for a trial, which are verified successfully.

For trials, standard Paddle behavior is that the trial is free, but customers must enter payment details for verification. See our Trials guide for further information about how subscription trials work and different approaches you may wish to take.

When a successful payment is made for a new subscription (or payment details for a trial are verified), Paddle fires two alerts to your configured webhook:

• subscription_payment_succeeded. Includes an initial_payment property. For new subscriptions, this is always set to 1.
• subscription_created. Includes a subscription_id property - a unique ID for this customer's subscription. Also includes links to hosted Paddle pages (cancel_url and update_url) which the customer can use to update their payment details or cancel the subscription if you choose to make these links available.

What next?

• Your backend system should permit the appropriate level of access to the purchased product/service for the customer (triggered by information received from Paddle via webhooks).

• The customer's subscription is set to a status of active or trialing, where:

Active Status Subscriptions	Trialing Status Subscriptions
Rebilled by Paddle, automatically.	Can be canceled by either the customer or the seller at any time before the trial period ends.
Can be updated by either the customer or the seller.	Moved to an active status automatically when the trial period ends.

For further information about using Paddle webhooks to manage customer access for your products/services, see our Access management using webhooks guide.

Rebilling

When a customer's next billing date is reached, Paddle attempts to take payment from the customer and notifies your backend system with the success or fail outcome.

This outcome determines the customer's subscription status and - in turn - it should determine the customer's level of access to your product/service.

Paddle calculates a customer's next billing date based on:

• The billing interval defined for the subscription plan in Paddle.
• The customer's initial payment date - i.e. the date the customer's subscription was created.

So, if a monthly subscription is purchased on 1st May 2022, the customer's next billing date would be 1st June 2022 and after that, 1st July 2022, etc.

Rebilling payment successful

If rebilling is successful, Paddle fires a subscription-payment-succeeded alert to your configured webhook.

For existing subscriptions, the payload for this alert includes an initial_payment property which is always set to 0.

What next?

• Your backend system should synchronize its records with required details from the webhook payload and continue to allow the appropriate level of customer access to the product/service.

Rebilling payment failed

If rebilling fails, Paddle fires a subscription-payment-failed alert to your configured webhook.

What next?

• Your backend system should synchronize its records with required details from the webhook payload and, if appropriate, adjust the level of customer access to the product/service.

• What happens after this depends on how Recover settings are configured in your Vendor Dashboard. You can define:

Item	Notes
Payment retries	Up to three payment retries can be defined for different intervals.
Failed payment action	Choose whether to pause, set to past_due or cancel subscriptions if all payment retries fail.
Failed payment notifications	Choose whether to send an email notification to customers for each failed payment attempt.
Canceled subscription notifications	Choose whether to send an email notification to customers if all payment retries fail and their subscription is canceled.

For further information see our Payment failures guide.

For further information about using Paddle webhooks to manage customer access for your products/services, see our Access management using webhooks guide.

Update subscription

An active subscription might be updated at any time. Updates can be initiated by the customer, the seller, or the Paddle rebilling process:

Action	Customer	Seller	Rebilling
Upgrade/downgrade subscription	Yes	Yes	No
Change subscription plan	Yes	Yes	No
Update payment details	Yes	No	No
Change billing date	No	Yes	No
Adjust subscription price	No	Yes	No
Pause subscription	No	Yes	Yes

When any update occurs, Paddle fires a subscription_updated alert to your configured webhook.

Paddle handles any prorated costs if an update prompts a change in the amount to be charged. For further information see our Upgrade & downgrade subscriptions guide.

For further information about pausing subscriptions, see our Access management using webhooks guide.

What next?

• Depending on the type of update made, the customer's subscription status and details may change.
• Your backend system should synchronize its records with required details from the webhook payload and, if appropriate, adjust the level of customer access to the product/service.

For further information about using Paddle webhooks to manage customer access for your products/services, see our Access management using webhooks guide.

Cancel subscription

An active subscription might be canceled by the customer, the seller, or the Paddle rebilling process:

Action	Customer	Seller	Rebilling
Cancel subscription	No	Yes	Yes

When a new subscription is created for a customer, Paddle generates a hosted web page for that subscription and provides the URL for this page in the subscription_created alert. We recommend making this link available to your customers, so subscriptions can be canceled on a self-serve basis.

Otherwise, subscriptions can be canceled by the seller via the Paddle Dashboard, or the Paddle API.

When a subscription is canceled, Paddle fires a subscription_cancelled alert to your configured webhook.

What next?

• Your backend system should synchronize its records with required details from the webhook payload and revoke customer access to the product/service.