Subscription renewal

Subscriptions renew automatically in Paddle unless canceled or paused. Paddle collects using a saved payment method, or sends an invoice that customers must pay.

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 are not renewed.

Events

This guide is overview of events that typically occur. Depending on the customer journey and how you build your workflows, not all events listed may occur, or additional events may occur.
We can't guarantee the order of delivery for webhooks. Store and check the occurred_at date against a webhook before making changes.

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

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:

Receipt

Your receipt from [company]

List of items purchased, along with totals and purchase date. Includes a PDF invoice for their records.

Recommended workflow

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.

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 complete billing and subscription management experience, see: Handle provisioning and fulfillment

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.

Handle provisioning and fulfillment

Paddle Checkout

Invoices

Sign up to get notified when our API evolves