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

# Dunning

> How Alguna recovers failed invoice payments automatically

Dunning is the process of recovering revenue when an invoice payment fails. In Alguna, dunning runs as an event-driven [Automation](/docs/automations/overview) rather than a separate engine, so every step — when to retry, what email to send, how to escalate — is configurable from the same place you build any other workflow.

***

## How It Works

```mermaid theme={null}
graph LR
    A[Payment fails] --> B[PaymentFailed event]
    B --> C{Automation matches?}
    C -->|Yes| D[Run dunning template]
    C -->|No| E[No action]
    D --> F[Request new payment method]
    D --> G[Retry charge]
    D --> H[Send reminder]
```

When a payment attempt fails, Alguna emits a `PaymentFailed` event containing the invoice ID, the customer account ID, and the failure reason. Any automation listening for that event runs.

***

## The Default Template

Every organization starts with a built-in template called **Failed Payment Notification**. It activates the first time a given invoice's payment fails and sends the customer a billing-information collection link so they can update their payment method.

| Property         | Value                              |
| ---------------- | ---------------------------------- |
| Trigger          | `Payment Failed` event             |
| Condition        | Invoice ID is present on the event |
| Execution policy | Once per invoice ID                |
| Default action   | Send billing-info collection email |

The "once per invoice" policy means the customer is not re-prompted on every retry of the same invoice — they're prompted on the first failure, and subsequent retries proceed silently against the updated payment method.

***

## Available Actions

Dunning automations can chain any of the following actions:

| Action                            | What It Does                                                               |
| --------------------------------- | -------------------------------------------------------------------------- |
| **Retry invoice payment**         | Re-attempts the charge using the customer's current default payment method |
| **Send billing info request**     | Emails the customer a hosted link to add or update a payment method        |
| **Send invoice reminder**         | Sends a payment reminder for an outstanding invoice                        |
| **Send invoice reminders (bulk)** | Sends reminders for multiple outstanding invoices in one run               |
| **Wait**                          | Pauses the workflow for a configurable duration before the next step       |
| **Condition**                     | Branches the workflow based on invoice or payment state                    |

The full action set is listed in the [automations reference](/docs/automations/reference).

***

## Configuration

Dunning is configured from the Automations page in the dashboard.

1. Open **Automations**.
2. Either enable the built-in **Failed Payment Notification** template, or click **Clone** to create an editable copy.
3. Add steps from the action list above. Common patterns:
   * **Wait → Retry payment → Wait → Retry payment → Send escalation reminder**
   * **Send billing info request → Wait 3 days → Retry payment → Send overdue handoff**
4. Activate the automation.

The trigger condition (`invoiceId != nil`) is enforced automatically — payment failures that aren't tied to an invoice (for example, a failed test charge) will not trigger the workflow.

***

## What the System Does Automatically

* Emits a `PaymentFailed` event whenever a payment attempt records a non-success status, regardless of whether dunning is configured.
* Deduplicates trigger runs per `invoiceId` for any template using the **Once** execution policy.
* Halts execution of any in-flight dunning run if the invoice transitions to `Paid` or `Void` between steps (the next condition step short-circuits).
* Logs every action attempt to the automation execution history, viewable on the run detail page.

## What the System Does Not Do Automatically

* Retry the charge without an explicit **Retry invoice payment** step in the workflow.
* Change the invoice status. Dunning is concerned with payment recovery; status transitions (for example, `Issued → Overdue`) are handled by [Collections](/docs/collections/overview).
* Send any communication outside the channels configured on each action.

***

## Edge Cases

**No invoice on the failure event.** Failed payments without an `invoiceId` (such as a one-off card validation or a payment retry against a deleted invoice) do not trigger the default template.

**Customer pays manually mid-run.** If the customer pays via wire or marks the invoice paid through the portal while a dunning run is waiting, the next condition step detects the new status and the run ends without sending further reminders.

**Subscription cancelled mid-run.** Dunning continues against the existing invoice. If you want runs to terminate on cancellation, add a condition step checking subscription status.

**Repeated failures on the same invoice.** With the default **Once** execution policy, the customer is prompted to update their billing info exactly one time per invoice. Subsequent retries are silent.

**Multiple invoices fail at once.** Each invoice gets its own independent run.

***

## Example

A \$4,200 invoice for a Net-30 subscription fails on the autocharge attempt because the card on file expired.

| Time  | Step                                     | Result                                                         |
| ----- | ---------------------------------------- | -------------------------------------------------------------- |
| T+0s  | Payment failed event emitted             | `invoiceId=inv_8a2f`, `reason=card_expired`                    |
| T+0s  | **Failed Payment Notification** triggers | Execution policy check passes (first failure for this invoice) |
| T+5s  | Get invoice action                       | Returns invoice details                                        |
| T+10s | Send billing info request                | Customer receives email with hosted update link                |
| T+2h  | Customer updates card via the link       | New default payment method saved                               |
| T+24h | Custom retry step (if added)             | Charge succeeds, invoice marked `Paid`                         |

If the customer hadn't updated their card, the invoice would have remained unpaid until the due date, at which point the [Collections](/docs/collections/overview) flow takes over.

***

## Impact on Other Parts of Alguna

* **Invoices**: dunning does not change invoice status. Status changes are driven by payment outcomes and the overdue cron.
* **Emails**: billing-info request and reminder emails are sent through the email templates system. You can customize copy under **Settings → Emails**.
* **Integrations**: failed payments from Stripe and other supported PSPs surface as `PaymentFailed` events through the [integrations marketplace](/docs/integrations/marketplace).
* **Hosted pages**: the billing-info collection link routes the customer to the [hosted customer portal](/docs/hosted/customer-portal).

***

## FAQ

**Can I disable dunning entirely?**
Yes. Deactivate the **Failed Payment Notification** template (and any other dunning templates you've enabled) on the Automations page. Payment failures will still emit events, but no workflow will run.

**Can I add SMS or Slack to my dunning sequence?**
Slack is built in: add a `send_slack_message` step to post to a connected workspace channel. SMS is not available as an automation action; for other channels, use `send_webhook` to call your own service. See [Automations Actions](/docs/automations/actions).

**Does dunning run on draft invoices?**
No. Dunning fires on the `PaymentFailed` event, which only emits for invoices that have been issued and attempted.

**What happens if the customer pays manually while a dunning run is waiting?**
The next condition step in the workflow checks invoice status and the run ends without further reminders.

**Where do I see dunning run history?**
On the Automations page, open the dunning template and view its execution history. Each run shows trigger inputs, every step that ran, and any errors.