Skip to content

Failed renewal payments and dunning

When a subscription renewal charge fails, Flint runs dunning for you. It marks the subscription past_due, emails the buyer a link to update their card, retries the charge on a schedule, and when the retries run out, cancels, pauses, or keeps the subscription past due under your settings. Your integration decides what access a past-due subscriber keeps, and can recover the payment early by charging a new card.

Each renewal is an order, so a recovered payment pays the same renewal order, with its receipt, tax, and refunds in one place. This guide assumes your subscriptions already renew, as in Subscription billing.

What happens when a renewal fails#

  1. What happens: A renewal charge fails
  2. Flint sends: subscription.past_due
    The subscription is past_due. missed_billing_at is the billing date that failed and next_retry_at is the first retry. Flint emails the buyer a payment-failure notice.
  3. What happens: An automatic retry fails and another is scheduled
  4. Flint sends: subscription.updated
    version advances and next_retry_at gives the new retry date.
  5. What happens: A retry succeeds
  6. Flint sends: subscription.payment_succeeded
    The subscription is active again and the period moves forward. The renewal order sends order.paid.
  7. What happens: The last retry fails
  8. Flint sends: subscription.dunning_exhausted
    Retries ran out. status shows the end action: canceled, paused, or still past_due.

With the default settings, a monthly subscription that fails to renew on March 1 is retried on March 2, 5, 10, and 17. If every retry fails, Flint cancels it after the March 17 attempt.

Nothing about the subscription changes your product's access on its own. Flint reports the state; you decide what a past_due subscriber can still use. A common choice is to keep access while Flint retries, show a banner asking for a new card, and revoke access only when the subscription is canceled.

The retry schedule#

Flint retries a failed renewal four times by default: 1, 4, 9, and 16 days after the charge first failed. dunning_retry_days in your subscription settings sets the length of that window, from 1 to 90 days, and Flint scales the retries to fit it. The last retry always falls on the final day of the window.

dunning_retry_daysRetries, in days after the failed charge
71, 2, 4, 7
16 (default)1, 4, 9, 16
302, 8, 17, 30

Each retry charges the subscription's current card for outstanding_money, the unpaid balance of the renewal order. Read next_retry_at for the next attempt instead of computing it.

Set the window and the end action with PATCH /v1/settings:

cURL
curl -X PATCH https://api.withflintpay.com/v1/settings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "subscriptions": {
      "dunning_retry_days": 30,
      "dunning_end_action": "pause"
    }
  }'

Permanent declines#

Some declines can't succeed on a retry, because the card is gone or the issuer said not to charge it again. A renewal or retry that fails with one of these codes gets no more automatic retries:

last_payment_error.codeWhat it means
expired_cardThe card has expired.
lost_card, stolen_cardThe cardholder reported the card lost or stolen.
fraudulentThe issuer suspects fraud.
authentication_requiredThe bank wants the buyer to authenticate, which an off-session charge can't do.
card_declined_do_not_retryThe issuer said not to charge this card again. A recurring charge needs the buyer's new authorization and a different card.
card_details_outdatedThe card's number or expiry changed. The buyer needs to update their card details.

After a permanent decline, Flint sends subscription.dunning_exhausted right away with the subscription still past_due, and the buyer's payment-failure email asks for a new card instead of promising a retry. Flint then waits for a working card until the retry window closes, dunning_retry_days after the renewal first failed. A payment retry that succeeds before then recovers the subscription. If none does, Flint applies the end action when the window closes. Later declines, including failed payment retries, don't extend the window.

A retry against the same card can't succeed, and the card networks charge fees for retrying a decline the issuer marked do not retry. Treat a failure code you don't recognize like payment_failed.

What a past-due subscription reports#

While a subscription is past_due, it reports what's owed and why the last charge failed:

Response
{
  "subscription_id": "sub_1kmn0aExample",
  "status": "past_due",
  "missed_billing_at": "2026-04-17T14:30:00Z",
  "next_retry_at": "2026-04-18T14:30:00Z",
  "outstanding_money": {"amount": 4872, "currency": "USD"},
  "recurring_subtotal_money": {"amount": 4500, "currency": "USD"},
  "last_payment_error": {
    "code": "insufficient_funds",
    "message": "The payment method has insufficient funds. Ask the customer to use a different payment method.",
    "failed_at": "2026-04-17T14:30:00Z",
    "remediation": {
      "retry": "none",
      "next_steps": "Update the subscription's payment method, then try again."
    }
  },
  "supported_actions": ["cancel", "change_plan"]
}
FieldWhat it tells you
missed_billing_atThe billing date whose payment failed.
next_retry_atWhen Flint retries next. null after a permanent decline or when no retry is scheduled.
outstanding_moneyWhat a retry collects: the renewal order's unpaid balance, including tax, shipping, and discounts. recurring_subtotal_money is only the items' price.
last_payment_errorThe latest decline. Buyer responses under /v1/me omit remediation and mask sensitive decline reasons.

These fields clear when the subscription leaves past_due. last_payment_error is read from the renewal order and its payment intent, so it changes without a subscription event and without a new version. Read the subscription again after payment_intent.payment_failed or the renewal order's order.* events, which carry subscription_id.

To find every subscription in recovery, list them with GET /v1/subscriptions?status=past_due.

Emails the buyer gets#

Flint emails the buyer at each point where they can act:

  • When the renewal first fails. A payment-failure notice with the amount and a link to update their card. After a permanent decline, it asks for a different card instead of saying Flint will try again. Flint sends this once per failed billing period, not on every automatic retry.
  • When dunning cancels or pauses the subscription. A cancellation notice that says the renewal was never paid, or a pause notice. The pause notice gives no resume date, because a dunning pause lasts until someone resumes it.
  • When a retry succeeds. The receipt for the renewal order, like any paid cycle.

Flint tells your integration about each step through the webhooks below. To send the buyer your own dunning emails, set customer_email_delivery.dunning to merchant_sends and send from subscription.past_due and subscription_payment_retry.failed. Customer email delivery covers the switch.

Recover with a new card#

A past-due subscription recovers when a charge succeeds, so the fix is a working card. Have the customer save a new card, as in Save a payment method, then point the subscription at it:

cURL
curl -X PATCH https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: card-sub-ada-002" \
  -d '{"payment_method_id": "pm_0newcardExample"}'

The card must be active and belong to the subscription's customer. A card still in setup fails with 409 ACTION_NOT_ALLOWED, reason status_not_reached, and changes nothing.

The next automatic retry charges the new card. To charge it now, start a payment retry:

cURL
curl -X POST https://api.withflintpay.com/v1/subscriptions/sub_1kmn0aExample/payment-retries \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: retry-sub-ada-001" \
  -d '{}'

The body must be empty or {}, and Idempotency-Key is required. The 201 response is a retry with subscription_payment_retry_id and status: "pending". Read it with GET /v1/subscriptions/{subscription_id}/payment-retries/{subscription_payment_retry_id}. It moves through processing to succeeded, with the order_id and payment_intent_id it charged, or to failed, with last_payment_error.

  • A failed manual retry doesn't use up an automatic retry or move the next one.
  • Replaying the same key returns the same retry and never charges again.
  • A retry needs a past_due subscription. Otherwise it returns 409 ACTION_NOT_ALLOWED, reason unsupported_state. A renewal held for delivery returns reason delivery_hold, and one waiting on stock returns inventory_wait; Flint charges those once the hold or wait clears.
  • A charge that needs the buyer to authenticate fails with authentication_required. Update the payment method first; an off-session retry has no authentication step.

Resume doesn't recover a past-due subscription. It returns 409 ACTION_NOT_ALLOWED, reason payment_required, because there's an unpaid cycle to collect.

Let buyers retry themselves#

In your own account pages, a buyer with a customer session can update their card with PATCH /v1/me/subscriptions/{subscription_id} and start a retry with POST /v1/me/subscriptions/{subscription_id}/payment-retries. Flint's buyer account follows the same rules.

Buyers get up to 3 retries per billing period, counting the ones you start. Your own retries aren't limited. Read the retry_payment entry in the subscription's buyer_actions to build the control:

  • retry_payment.remaining_retries and max_retries are present while the subscription is past_due, even when the action is unavailable.
  • unavailable_reason: "limit_reached" means no retries are left this period.
  • unavailable_reason: "in_progress" means a retry is running. Read the one named in retry_payment.active_subscription_payment_retry_id with GET /v1/me/subscriptions/{subscription_id}/payment-retries/{subscription_payment_retry_id} until it finishes.
  • A buyer who scheduled a cancellation has to undo it first. Until then, their retry returns 409 ACTION_NOT_ALLOWED, reason cancellation_scheduled.

What recovery does to the billing date#

On a flint schedule, a payment collected more than 24 hours after the billing date that failed starts a new period on the payment day, and billing_anchor_day moves to that day. A monthly subscription due March 1 that recovers on its March 5 retry renews on April 5, May 5, and so on. A payment within 24 hours keeps the original schedule. An external schedule keeps the dates you set.

When dunning ends#

The end action decides what happens when the last retry fails, or when the window closes after a permanent decline. It's set separately for each billing schedule owner:

SettingApplies toDefault
subscriptions.dunning_end_actionSubscriptions on a flint schedulecancel
subscriptions.external_dunning_end_actionSubscriptions on an external schedulenotify_only
End actionResult
cancelThe subscription is canceled with cancellation_reason: "payment_failed", and Flint sends subscription.canceled. A canceled subscription can't come back; create a new one if the buyer returns.
pauseThe subscription is paused with pause_reason: "payment_failed", and Flint sends subscription.paused. Resuming it collects the unpaid period first, so it's past_due until that payment succeeds.
notify_onlyThe subscription stays past_due, and Flint sends only subscription.dunning_exhausted. It stays that way until you retry the payment, pause it, or cancel it.

When the final retry cancels or pauses the subscription, Flint sends subscription.dunning_exhausted and that specific event without a separate subscription.updated. After a permanent decline, subscription.dunning_exhausted was already sent, so the end action sends only its own event.

Cancel during recovery#

A cancellation at period end on a past_due subscription is scheduled for next_retry_at, in place of that retry. A past_due subscription without next_retry_at, such as one waiting after a permanent decline, has no period end to cancel at, so send cancel_immediately: true.

Trials and first payments#

A first charge that fails, including the first charge when a trial ends, moves the subscription to past_due and follows the same path. When a retry succeeds, the subscription becomes active and Flint sends subscription.activated, exactly once.

Interrupted billing#

If Flint's billing recovers from an interruption while a retry is scheduled, the window counts from missed_billing_at, which can make it shorter than the original. A subscription already waiting for a new card when billing recovers keeps waiting without a deadline.

Webhooks#

Handle these events to keep access and your own records in step with dunning:

Every declined charge also sends payment_intent.payment_failed. Webhook delivery is at least once and unordered, so deduplicate by webhook_event_id and read the subscription before you grant or revoke access. The webhook catalog has every payload.

Test it with a test clock#

In a sandbox, a test clock runs the whole schedule in minutes. Fail a renewal and walk the retries has every request. In short:

  1. Create a customer on a test clock, save a card, and create a subscription.
  2. Save a second card with . It attaches, then every charge on it fails. PATCH the subscription to use it.
  3. Advance the clock to next_billing_at and wait for test_clock.ready. The renewal fails, the subscription is past_due, and next_retry_at is one day later.
  4. Advance to each next_retry_at in turn. With the default settings, a renewal due February 15 is retried on February 16, 19, and 24, and March 3. After the last one, you receive subscription.dunning_exhausted and the end action's event.
  5. To test recovery instead, PATCH the subscription back to a working card and start a payment retry. The subscription returns to active and sends subscription.payment_succeeded.

The retry window and permanent-decline deadlines run on the clock's time too. No account yet? Sign up and test dunning in your sandbox.

Coming from Stripe Billing#

<!-- Stripe facts from https://docs.stripe.com/billing/revenue-recovery/smart-retries, checked 2026-11-21. -->

Stripe's Smart Retries choose retry times with a model, configured for up to 8 retries within 2 weeks on new accounts. After a hard decline such as lost_card, Stripe keeps scheduling retries but runs them only once a new payment method appears. When recovery fails, Stripe cancels the subscription, marks it unpaid, leaves it past_due, or pauses it.

Flint's schedule is fixed and visible ahead of time in next_retry_at. A permanent decline stops automatic retries at once, sends subscription.dunning_exhausted, and keeps the window open for a new card. Flint's end actions are cancel, pause, and notify_only. Buyers can retry their own payment through the API with a per-period limit, and every attempt pays the same renewal order. Migrating from Stripe maps the rest of Stripe Billing.

Ready to stop losing renewals to failed cards? Create a Flint account and run your first failed renewal in a sandbox.

Was this helpful?