Reasons for Invoice Failure

No Payment Method Available 💳

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 configured and grace period passes)
4. Finally FAILS only when dunning expires (all dunning events are exhausted)
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 and reaches the final dunning event is the most common reason for invoice failure.

Process:

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

Hard Declined Transactions 🚫

When a payment transaction is hard declined 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 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
Failed invoices are NOT automatically retried when new payment methods are added - they must be manually settled via the /settle API endpoint.