---
title: "Reasons for Invoice Failure"
slug: "reasons-for-invoice-failure"
updated: 2025-11-13T09:44:48Z
published: 2025-11-13T09:44:48Z
canonical: "help.frisbii.com/reasons-for-invoice-failure"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.frisbii.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasons for Invoice Failure

## **No Payment Method Available** 💳

1. **Subscription Invoices (Recurring):**

When no payment method is available, the invoice **does NOT fail on first attempt**.

**What happens:**
  1. **First Processing Attempt:**

Invoice stays in **PENDING** state

We set the `failed` timestamp on the invoice

Schedules next retry using default delay
  2. **Continues retrying** based on scheduled intervals
  3. **Eventually enters DUNNING** (if [dunning plan](/frisbii/docs/dunning-management#create-a-new-dunning-plan) configured and grace period passes)
  4. **Finally FAILS** only when **dunning expires** (all dunning events are exhausted)
2. **Customer or Charge Invoices:**

These **DO fail immediately** when no payment method is available.

---

## **Dunning Plan Expiration** ⏰

When an invoice goes through the [dunning process](/frisbii/docs/dunning-management#create-a-new-dunning-plan) and reaches the **final dunning event** is the most common reason for invoice failure.

**Process:**

1. Invoice enters **DUNNING** state when payment attempts fail
2. Dunning plan sends notifications at scheduled intervals
3. When the last dunning event is reached, the dunning expires
4. Invoice transitions from **DUNNING** → **FAILED**

---

## **Hard Declined Transactions** 🚫

When a payment transaction is [hard declined](/frisbii/docs/test) by the payment provider:

**For Customer and Charge Invoices:**

- Immediately fails on hard decline

**For Subscription Invoices:**

- First settle attempt with hard decline → invoice fails
- Or during settle-later processing

---

## **Retry Duration Exceeded** ⏱️

For invoices with **soft declines** or **processing errors**, the system automatically retries payment collection according to a configured **Dunning Plan**. When the total retry duration is exceeded without successful payment, the invoice enters a final **failure** state.

**Process:**

- When an invoice first fails with a soft decline or processing error, the invoice enters a dunning state.
- The total retry duration consist of
  - **Grace Period**
  - **Retry Schedule**
- The system calculates elapsed time by summing all schedule intervals
  - **Total Retry Duration = Grace Period + Sum of Schedule Intervals**

Let's say you have:

- **Grace Period**: 1 day
- **Schedule**: [3, 2, 7] days
- **Invoice Due Date**: January 1, 2025

| Day | Event | Description |
| --- | --- | --- |
| Day 1 (Jan 1) | Payment fails | Soft decline detected, dunning starts |
| Day 1 | Grace period begins | 1-day grace period (can be skipped for hard declines) |
| Day 1 | 1st email sent | "Payment declined" notification |
| Day 4 (Jan 4) | Retry #1 | Wait 3 days → Attempt payment again + 2nd email |
| Day 6 (Jan 6) | Retry #2 | Wait 2 days → Attempt payment again + 3rd email |
| Day 13 (Jan 13) | ⏱️ Duration exceeded | Wait 7 days → Final subscription action (Expire or On Hold or Nothing) → Invoice Failed |

---

## **Manual Fail via API** 🔧

Invoices can be manually failed through the [API endpoint](https://docs.frisbii.com/reference/failinvoice) or forced failure.

1. State changes to **FAILED**

2. `Failed` timestamp is set

3. Dunning is cleared

4. Next processing is cleared (no automatic retries)

5. `INVOICE_FAILED` webhook event is triggered

6. Subscription/customer status are updated

> [!NOTE]
> Note
> 
> **Failed** **invoices** are **NOT** automatically retried when new payment methods are added - they must be manually settled via the `/settle` [API endpoint](https://docs.frisbii.com/reference/settle).