Dunning

Dunning is the process of recovering revenue when an invoice payment fails — a declined card, an expired one, a bank debit that bounced. In Alguna, dunning is not a separate engine: a failed payment emits a payment_failed event, and any automation listening for it runs. That means every step — when to retry, what to email, when to escalate — is built from the same actions as any other workflow. Use this page to understand the default behaviour and to design your own sequence. Dunning is about failed payments. Invoices that simply go unpaid past their due date are handled by Collections; Agentic Collections (beta) can take over both. There is no public API for configuring dunning — it is set up on the Automations page — but the payments it acts on are readable through GET /payments and the payment.updated webhook. See How Alguna Works for the payment model.

How it works

When a payment attempt records a non-success status, Alguna emits payment_failed with the invoice ID, the customer account ID, and the failure reason. The same moment is visible outside Alguna as a payment.updated webhook with status: "failed".

The default template

Every organization starts with a built-in template called Failed Payment Notification. It runs the first time a given invoice’s payment fails and emails the customer a hosted link to add or update a payment method.

Property	Value
Trigger	`payment_failed`
Condition	`invoiceId != nil`
Execution policy	`once` per `invoiceId`
Steps	`get_invoice` → `send_billing_info_request` (with payment-method capture on)

“Once per invoice” means the customer is prompted on the first failure only. Later retries of the same invoice run silently against whatever payment method is now on file. A second built-in template, Notify on failed payment, posts a Slack alert to your team on every payment_failed event. It is a notification for you, not outreach to the customer.

Available actions

A dunning automation can chain any of these:

Action	What it does
`retry_invoice_payment`	Re-attempts the charge with the customer’s current default payment method
`send_billing_info_request`	Emails a hosted link to add or update a payment method
`send_invoice_reminder`	Sends a payment reminder for one outstanding invoice
`send_invoice_reminders_bulk`	Sends reminders for several outstanding invoices in one run
`send_card_expiration_reminder`	Warns the customer before a saved card expires (pair with the `card_expiring` trigger to prevent failures)
`send_slack_message` / `send_webhook` / `send_email`	Notify your team or call your own systems
Delay	Pauses the workflow for a duration before the next step
Condition	Branches on invoice or payment state, e.g. `status == 'paid'`

The full list, with inputs, is in Automation actions.

Configuration

Open Automations.
Enable the built-in Failed Payment Notification template, or click Clone to get an editable copy.
Add steps. Common shapes:
- Wait 1 day → retry_invoice_payment → wait 3 days → retry_invoice_payment → send_invoice_reminder
- send_billing_info_request → wait 3 days → retry_invoice_payment → send_slack_message to your AR channel
Activate the automation.

The trigger condition invoiceId != nil is set on the template, so payment failures not tied to an invoice (for example a failed card validation) do not start a run.

What the system does automatically

Emits payment_failed on every unsuccessful payment attempt, whether or not any automation is listening.
Deduplicates runs per invoiceId for templates with the once execution policy.
Ends an in-flight run when a condition step sees the invoice is paid or void.
Records every step of every run in the automation’s execution history.

What it does not do

Retry a charge without an explicit retry_invoice_payment step.
Change the invoice status. issued → overdue is driven by the due date and handled by Collections; → paid by a successful payment.
Send anything outside the actions you configured.

Edge cases

No invoice on the failure. A failure without an invoiceId (a one-off card validation, or a retry against a deleted invoice) does not match the default template. Customer pays manually mid-run. If the customer pays by wire — and you record it with mark-as-paid — or pays through the portal while a run is waiting, the next condition step sees the new status and the run ends. Subscription cancelled mid-run. The run continues against the existing invoice. Add a condition on subscription status if you want it to stop. Repeated failures on one invoice. With once, the customer is asked for billing info exactly one time per invoice. Later retries are silent. Several invoices fail at once. Each invoice gets its own run.

Example

A $4,200 invoice on a net_30 subscription fails its AutoPay attempt because the card on file has expired.

Time	Step	Result
T+0s	`payment_failed` emitted	`invoiceId=inv_8a2f`, reason from the processor
T+0s	Failed Payment Notification triggers	First failure for this invoice, so the `once` policy passes
T+5s	`get_invoice`	Returns invoice details
T+10s	`send_billing_info_request`	Customer receives the email with the hosted update link
T+2h	Customer updates the card	New default payment method saved
T+24h	Your added `retry_invoice_payment` step	Charge succeeds; invoice becomes `paid`; `invoice.paid` webhook fires

If the customer had not updated the card, the invoice would have stayed issued until its due date, when Collections takes over.

Watching from outside Alguna

You do not need to be inside an automation to react to failures:

curl "https://api.alguna.io/payments?customer_id=cust_abc123&limit=20&offset=0" \
  -H "Authorization: Bearer $ALGUNA_API_KEY" \
  -H "Alguna-Version: 2026-04-01"

import os

import requests

response = requests.get(
    "https://api.alguna.io/payments",
    headers={
        "Authorization": f"Bearer {os.environ['ALGUNA_API_KEY']}",
        "Alguna-Version": "2026-04-01",
    },
    params={"customer_id": "cust_abc123", "limit": 20, "offset": 0},
    timeout=10,
)
response.raise_for_status()

failed = [p for p in response.json()["data"] if p["status"] == "failed"]
for payment in failed:
    print(payment["id"], payment["failed_at"], [a["invoice_id"] for a in payment["allocations"]])

Or subscribe to payment.updated and look for status: "failed". See Invoicing Customers and Webhooks.

Impact on other parts of Alguna

Invoices: dunning does not change invoice status; payment outcomes and the due date do.
Emails: the billing-info request and reminder emails are the billing_information_request and invoice_reminder_overdue / invoice_reminder_due templates under Settings → Emails.
Integrations: failures reported by Stripe and other connected processors surface as payment_failed events.
Hosted pages: the billing-info link takes the customer to the customer portal to update their payment method.

FAQ

Can I disable dunning entirely? Yes. Deactivate Failed Payment Notification and any other automation on the payment_failed trigger. Failures still emit events; nothing runs. Can I add Slack or a webhook to my sequence? Yes — send_slack_message posts to a connected workspace channel and send_webhook calls your own endpoint. SMS is not an automation action. See Automation actions. Does dunning run on draft invoices? No. payment_failed only emits for invoices that were issued and had a payment attempted. Where do I see dunning run history? On the Automations page, open the automation and view its execution history: trigger inputs, each step, and any errors.

Overview

Guides

Getting Started

Customers

Pricing & Packaging

Quotes (CPQ)

Subscriptions

Entitlements

Invoices

Credits & Wallets

Usage Metering

Approval Workflows

Automations

Collections

Tax Management

Hosted Pages

Revenue & Accounting

Multi-Currency

Data & Exports

AI

How it works

The default template

Available actions

Configuration

What the system does automatically

What it does not do

Edge cases

Example

Watching from outside Alguna

Impact on other parts of Alguna

FAQ

​How it works

​The default template

​Available actions

​Configuration

​What the system does automatically

​What it does not do

​Edge cases

​Example

​Watching from outside Alguna

​Impact on other parts of Alguna

​FAQ

How it works

The default template

Available actions

Configuration

What the system does automatically

What it does not do

Edge cases

Example

Watching from outside Alguna

Impact on other parts of Alguna

FAQ