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 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

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.

---

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.
• 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 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.
• Hosted pages: the billing-info collection link routes the customer to the 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.

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.