Subscription renewal

Renewals are the defining feature of subscription business models. Subscription renewals happens at the end of a billing period when a customer continues their subscription and is billed for the next billing period.

A renewal is successful where payment is collected successfully. If unsuccessful, a subscription becomes past due.

How it works

At the end of the current billing period, Paddle automatically creates a transaction for the next billing period. This transaction is for any recurring items on the subscription, along with any one-time charges or subscription changes that have been billed on the next billing period.

Transactions are automatically created for subscription renewals, even for manually-collected subscriptions:

• For automatically-collected subscriptions, Paddle creates a transaction and collects for it automatically using the payment method on file. It becomes past due if a collection attempt fails.
• For manually-collected subscriptions, Paddle creates and issues an invoice. Customers must pay it manually before the payment terms elapse, otherwise it becomes past due.

Subscriptions that are scheduled to pause or cancel aren't renewed.

Events

Emails

For compliance reasons, Paddle sends emails for subscription lifecycle events.

When a subscription renews, Paddle sends:

Recommended workflow

1. Listen for events

   We recommend that you listen for:

   subscription.updated	Get notified when a subscription is updated.
   transaction.created	Get notified when a transaction is created. Transactions with the origin of subscription_recurring are for renewals.
   transaction.completed	Get notified when a transaction is completed. This means it's fully paid and Paddle has completed processing.

2. Update information in your database

   Update the record for a subscription in your database for the renewal based on webhooks received. As well as checking and storing the occurred_at date against notifications, you'll typically need to update:

   Description	Field name	Reason to store
   Subscription status	subscription.status	Used to determine if a renewal was successful. Status is past_due where automatic collection fails, or where an invoice is unpaid and its payment terms have elapsed.
   Next billing date	subscription.next_billed_at	Used to determine when a subscription renews if active.

   You may like to store and update other fields if you want to build a more comprehensive billing and subscription management experience. To learn more, see Handle provisioning and fulfillment

3. Provision

   Provision so that a customer has continued access to your app.

    

   Use the subscription.status field to determine whether a subscription should have access to your app. Where status is active or past_due, customers should have full access to your app.

Related pages