Paddle Billing

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


This guide is overview of events that typically occur. Depending on your 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.

  1. Subscription renews

    subscription.updatedThe subscription and its items are updated with new previously_billed_at and next_billed_at dates, and the current_billing_period is updated.
    transaction.createdPaddle 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.billedOccurs because the transaction status changes to billed.
  2. Payment collected successfully

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


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

When a subscription renews, Paddle sends:

Screenshot showing a receipt email. It includes a list of items, total, and billing date.


Your receipt from [company]

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

Recommended workflow

  1. Listen for events

    We recommend that you listen for:

    subscription.updatedGet notified when a subscription is updated.
    transaction.createdGet notified when a transaction is created. Transactions with the origin of subscription_recurring are for renewals.
    transaction.completedGet 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:

    DescriptionField nameReason to store
    Subscription statussubscription.statusUsed 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 datesubscription.next_billed_atUsed 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