# Track dunning recovery from failed invoices

> Measure failed-payment recovery from invoice failure through retry, card update, recovery, or cancellation for subscription revenue.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/dunning-recovery-funnel
- Execution mode: on_demand
- Immutable automation template: none
- Applies to: b2c-saas, b2b-saas, devtools-api
- Required example events: invoice_payment_failed, payment_method_updated, invoice_payment_recovered
- Required Agentry resources: none declared
- Do not use when:
  - Do not use until the example events are mapped to observed project signals, the current onboarding state is verified, and live event/property reads prove the required data is present.
  - Do not recommend this for products without a real revenue lifecycle or an equivalent paid-account signal.
- Ask before using:
  - Which observed events map to invoice_payment_failed, payment_method_updated, invoice_payment_recovered? Is the current onboarding state verified, and do live event/property reads show non-synthetic traffic for them?
  - Which live properties provide invoice_payment_failed.account_id, invoice_payment_failed.invoice_id, invoice_payment_failed.amount, payment_method_updated.account_id, invoice_payment_recovered.account_id, invoice_payment_recovered.invoice_id, and which stable user or account identifier joins the signals?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this matters

Failed payments are often recoverable churn. A dunning funnel shows whether users update cards, retries recover revenue, or accounts silently cancel.

## What you get

- Recovery rate after failed invoices
- Time to recovery
- Cancellations after dunning
- Revenue at risk and recovered

## Walk through it

**You:**
> How effective is our dunning flow?

**Agent:**
> I'll stitch billing webhook events into a recovery funnel.

```text
Endpoint: POST /v1/projects/:project_id/analytics/query
Exact shape: /v1/openapi.json?path=%2Fv1%2Fprojects%2F%7Bproject_id%7D%2Fanalytics%2Fquery&method=post
Custom HogQL goes in the OpenAPI-defined `query` field.
Concept fields:
  query: "SELECT event, count(DISTINCT properties.invoice_id) AS invoices, sum(toFloat(properties.amount)) AS amount FROM events WHERE event IN ('invoice_payment_failed','payment_method_updated','invoice_payment_recovered','subscription_canceled') AND timestamp > now() - INTERVAL 60 DAY GROUP BY event ORDER BY invoices DESC"
```

## The output

The agent returns recovery rate, lost revenue, and suggested actions such as improving retry timing or card-update emails.

## Setting it up

Emit billing lifecycle events from Stripe or your subscription provider webhook handler.

## Variations

- *"Segment recovery by plan."*
- *"Find accounts with repeated payment failures."*
- *"Draft a Slack digest for at-risk revenue."*