Subscription past due

A subscription becomes past due where payment for a renewal isn't collected successfully. If successful, a subscription renews.

Paddle Retain works to recover failed payments for automatically-collected subscription renewals.

How it works

Manually-collected subscriptions are paid by invoice. They become past due when payment terms against invoices for subscription renewals elapse. As customers pay manually-collected subscriptions themselves, Paddle doesn't take any action when they're past due.

How to configure payment recovery

Events

Payment recovered successfully

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 collection fails

   transaction.updated	Payment fails using payment method on file. The transaction is updated with information about the unsuccessful payment attempt. Its status changes to past_due.
   transaction.payment_failed	Occurs because payment fails using payment method on file.
   transaction.past_due	Occurs because the transaction status changes to past_due.
   subscription.updated	The subscription status changes to past_due.
   subscription.past_due	Occurs because the subscription status changes to past_due.

3. Unsuccessful retry attempt — Paddle Retain only

   Paddle Retain works with live data for your billing platform. This means you can't integrate with test or sandbox accounts.

   This step only occurs if you've integrated with Paddle Retain.

    

   Paddle Retain attempts to automatically recover this payment for you. Depending on how you've configured payment recovery, Retain automatically retries payments at the best time for success.

    

   For each recovery attempt where payment is unsuccessful, the following events occur:

   transaction.payment_failed	Payment fails using payment method on file. The transaction is updated with information about the unsuccessful payment attempt.

   If a retry attempt is successful, events for payment collection for a successful renewal occur.

4. Customer updates payment method successfully

   Payment recovery emails, SMS, and in-app notifications sent by Paddle Retain prompt customers to update their payment method.

    

   If you haven't integrated with Paddle Retain, customers can update their payment details using the customer portal or a workflow you've built.

    

   If a customer updates their payment method, the following events occur:

   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.
   subscription.updated	The subscription status is updated to active.
   subscription.activated	Occurs because the subscription status changes to active.
   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.

Payment not recovered

When all payment recovery attempts are exhausted, Paddle Retain automatically pauses or cancels a subscription for you. Events for subscription paused immediately or subscription canceled immediately occur.

If you haven't integrated with Paddle Retain, Paddle automatically cancels a subscription for you. Events for subscription canceled immediately occur.

Emails — Paddle Retain only

Paddle Retain takes care of dunning for you. Our team of experts send millions of messages, testing and optimizing the content and cadence across hundreds of thousands of transactions. We're constantly improving emails for the best chance of payment recovery, so we haven't included full previews here.

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.
   subscription.past_due	Get notified when a subscription is past due. This means automatic collection failed, or an invoice is unpaid and its payment terms have elapsed.
   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.
   subscription.activated	Get notified when a past due subscription becomes active. The subscription status is updated to active. This means that payment method was updated successfully for a past due subscription.

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. Update your frontend

   You can't make changes to items on a past due subscription. Build logic in your frontend to prevent changes to subscriptions that are in dunning.

    

   We recommend providing a way for customers to update their payment method. You can use Paddle Retain to display in-app notifications to customers to prompt them to update their payment method.

4. Provision

   Provision so that a customer has the correct level of 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. Where payment recovery attempts fail, follow the recommended workflow for subscription paused or subscription canceled.

Related pages