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. Your customer must pay it manually before the payment terms elapse, otherwise it becomes past due.

Subscriptions that are scheduled to pause or cancel are not renewed.

Events

1. Subscription renews

   subscription.updated	The subscription and its items are updated with new previously_billed_at and next_billed_at dates, and the current_billing_period is updated.
   transaction.created	Paddle creates a transaction for recurring items on the subscription, as well as any prorated or one-time charges that were set to be billed on the next billing period. Its status is billed, meaning no changes can be made to the transaction. Its origin is subscription_recurring.
   transaction.billed	Occurs because the transaction status changes to billed.

2. Payment collected successfully

   transaction.updated	The transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
   transaction.paid	Occurs because the transaction status changes to paid.
   transaction.updated	An invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
   transaction.completed	Occurs because the transaction status changes to completed.

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 is 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'd like to build a more complete billing and subscription management experience, 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