Subscription past due

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

Paddle Retain automatically handles payment recovery for subscription renewals.

How it works

When payment fails for an automatically-collected subscription, the subscription status changes to past_due and it enters dunning. This is the process where Paddle Retain works to automatically recover the payment for you.

With Paddle Retain, you can:

• Automatically reattempt to collect for payment using the previously declined payment method. Collection attempts happen over about a week.
• Send optimized payment recovery emails, SMS, an in-app notifications that prompt customers to update their details.

When all payment recovery attempts are exhausted, Paddle Retain automatically pauses or cancels a subscription for you. You can choose whether subscriptions should pause or cancel when configuring Retain.

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 using Paddle Retain

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

   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 a customer updates their payment method using Paddle Retain, 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.

Emails

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