Dunning

When a subscription payment fails, RevKeen automatically enters a dunning process that intelligently retries payments while keeping your customers informed. This process typically recovers 30-50% of failed payments without any manual intervention.

How Dunning Works

When a payment fails, RevKeen classifies the decline code and determines the best recovery strategy:

1. Classify Decline -- Analyze the decline code to determine if it's a temporary (soft) or permanent (hard) decline.
2. Smart Retry -- Schedule automatic retries based on decline type. Soft declines get retried on Days 1, 3, and 7.
3. Notify Customer -- Send targeted emails at each stage to encourage customers to update their payment method.

Decline Code Categories

Default Retry Schedule

The default retry schedule balances recovery rates with customer experience:

You can customize the retry schedule and grace period in your merchant settings. Longer grace periods may recover more payments but also increase revenue delay.

Grace Period Configuration

The grace period determines how long customers retain access while their payment is being retried. Configure these settings per-merchant:

Direct Debit collections

Failed Bacs Direct Debit collections follow their own recovery path, configured in Settings → Direct Debit:

• Insufficient funds and other soft failures are collected again automatically. Each attempt is a new Direct Debit for the same invoice, taken the configured number of UK working days after the failure (weekends and bank holidays are skipped). Your customer gets an advance notice before every attempt.
• When the attempts run out, or the failure can't be retried (for example, the account is closed), RevKeen emails your customer a link to pay the invoice by card instead. The invoice stays open until it's paid.
• Direct Debit attempts can't be started by hand. "Retry now" in your Inbox shows when the next scheduled attempt is instead, because every attempt needs its own advance notice to your customer.
• New merchants start with 3 attempts, 7 working days apart. If you already had a setting saved, including 0 attempts, RevKeen keeps it.
• A renewal always gets that request. For a subscription renewal, your customer is asked to pay by card even if your setting is "Do nothing automatically". "Ask the customer to contact the business" keeps its own email.
• The subscription then has until your maximum dunning days to pay (30 by default), counted from the day Direct Debit stopped trying. If the invoice is still unpaid then, the subscription becomes unpaid, or cancelled if your dunning settings cancel, as a card subscription does. Access through connected apps is removed. The invoice stays open, so a late payment is still recorded, and paying it makes an unpaid subscription active again.
• This is the Smart Payment recovery path: Direct Debit first, with a consent-gated card fallback.

When the invoice is no longer owed

If you void a subscription invoice, or mark it uncollectible or refunded, RevKeen never charges it and never reopens it. This holds for card and Direct Debit alike:

• A renewal whose invoice for the period is no longer owed is not collected. The subscription moves on to its next billing period, and the invoice keeps the status you gave it.
• An invoice waiting for your approval is not collected either, and the subscription stays on the same period until you approve it. The next renewal run after approval collects it once.
• If the subscription was in dunning, retries stop. The subscription becomes active again. Your customer is not emailed.
• If nothing is left to pay on the invoice (for example, earlier payments or credits already cover it), retries stop the same way, and the invoice keeps its status.

When renewals are paused on your side

Sometimes a renewal can't be collected for a reason that has nothing to do with your customer's card: card payments aren't live on your account yet, card payments have been suspended, or your identity verification isn't complete.

In that case RevKeen pauses the renewal instead of treating it as a failed payment:

• your customer is not charged, and gets no failed-payment or dunning email;
• the subscription keeps its status and doesn't enter dunning or its grace period;
• you get one email and one Inbox alert when this starts, and a banner stays at the top of your dashboard until it's resolved;
• once card payments are live again, the waiting renewals are collected automatically, usually within an hour. You don't need to retry them.

RevKeen never pauses your subscriptions for you. If you'd rather pause, cancel or void them yourself, you can still do that from the subscription page.

Dunning Email Sequence

RevKeen sends a series of emails to help customers recover their subscription:

Day 0: Payment Failed -- "We couldn't charge your card. Please update your payment method to avoid service interruption."

Day 1: Retry Failed -- "Still having trouble charging your card. We'll retry again soon, but please update your payment method."

Day 3: Urgent Action Needed -- "Action needed to avoid service interruption. Update your payment method now."

Day 7: Service Suspended -- "Your subscription has been suspended due to payment failure. Update your payment method to restore access."

Subscription States During Dunning

When auto_cancel_unpaid is set to true, the subscription will automatically cancel after all retries are exhausted. Otherwise, it remains in unpaid status until manually resolved.

Handling Dunning via API

Dunning runs automatically. Through the API you can read where a subscription is in its recovery, and take a one-off payment yourself if you need to.

Check Subscription Dunning Status

client.subscriptions.get returns the subscription with a dunning summary while it is past due.

import { RevKeenClient } from "@revkeen/sdk";

const client = new RevKeenClient({ apiKey: process.env.REVKEEN_API_KEY! });

const { data: subscription } = await client.subscriptions.get("sub_xxxxxxxx");

if (subscription.status === "past_due" && subscription.dunning?.is_in_dunning) {
  console.log("Retry", subscription.dunning.retry_count, "of", subscription.dunning.total_possible_retries);
  console.log("Next retry:", subscription.dunning.next_retry_at);
  console.log("Access restricted:", subscription.dunning.access_restricted);
}

Find the invoices being retried

const { data: invoices } = await client.invoices.list({ customerId: subscription.customer_id });

Retries are scheduled by RevKeen; there is no public API call that forces an early retry of an invoice. To take a one-off card payment from the customer instead, create and confirm a payment intent, or send them the invoice again with client.invoices.send.

Dunning Webhooks

RevKeen does not publish dedicated dunning webhook events yet. Use these public events, from the event catalogue, to follow a recovery:

To see whether a subscription is still in dunning, read it with client.subscriptions.get as shown above.

Webhook Handler Example

app.post("/webhooks/revkeen", async (req, res) => {
  // Verify the signature and record the event before acting on it:
  // see the Signing and Receiving webhook guides.
  const event = req.body;
  // data.object can be absent on a truncated delivery; fetch the resource if so.
  const object = event.data?.object;

  switch (event.type) {
    case "payment.failed":
    case "collection.failed":
      // Log the failure; RevKeen schedules the retry
      console.log("Payment attempt failed:", object?.id);
      break;

    case "invoice.paid":
      // The invoice was paid: restore access if you restricted it
      await restoreAccess(object?.customer_id);
      break;

    case "subscription.canceled":
      await endAccess(object?.id);
      break;
  }

  res.status(200).send("OK");
});

Best Practices

• Keep Cards Updated -- Encourage customers to update their card from the customer portal before it expires.
• Grace Period Length -- 7 days is the sweet spot for most businesses -- long enough to recover payments, short enough to minimize revenue lag.
• Custom Retry Schedule -- For high-value subscriptions, consider extending retries to 14 days with more attempts. For low-value, shorter schedules reduce bad debt.
• Monitor Recovery Rates -- Track your dunning recovery rate in analytics. Aim for 30-50% recovery of failed payments. Below 20% may indicate card quality issues.

Warning: Never disable dunning emails completely. They are proven to significantly improve recovery rates and reduce involuntary churn.

Related

• Subscriptions -- Learn about the full subscription lifecycle
• Payments and Refunds -- Processing payments and issuing refunds

Owner: david · Reviewed 1 Oct 2026 · Next review 30 Oct 2026