Dunning Campaigns

This page explains the concepts. To turn it on step by step, follow the dunning setup guide.

Automated Payment Recovery

Dunning campaigns automate failed payment recovery through multi-step communication sequences. When a payment fails, Recurso executes your configured steps — sending emails, SMS messages, and optionally activating a payment wall.

Multi-channel sequences — Combine email, SMS, and payment wall steps
Configurable timing — Set day offsets for each step relative to the failure date
Payment wall — Block access with configurable grace periods
Custom templates — Use your own email/SMS templates or inline content
Default campaigns — Automatically apply to all failed payments

Dunning campaigns handle customer communication. For optimizing retry timing, see Smart Payment Retry, which uses reinforcement learning to determine when to retry the actual payment.

Campaign Lifecycle

Create a Campaign

curl -X POST https://api.recurso.dev/v1/dunning-campaigns \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard Recovery",
    "trigger_event": "payment_failed"
  }'

Campaign Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Campaign name
`trigger_event`	string	Yes	What starts the campaign — `payment_failed` or `invoice_overdue`

The campaign is a container; the recovery behaviour (including the payment wall) lives on its steps, added next.

Add Campaign Steps

Build your recovery sequence by adding steps at specific day offsets.

Channel	Description
`email`	Send an email notification to the customer
`sms`	Send an SMS message to the customer
`in_app`	Surface an in-app notice

A step can also raise the payment wall by setting is_payment_wall: true (independent of channel). Each step fires delay_hours after the trigger event. POST /v1/dunning-campaigns/{id}/steps:

Hour 0: immediate email

curl -X POST https://api.recurso.dev/v1/dunning-campaigns/{campaign_id}/steps \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "step_order": 1, "channel": "email", "delay_hours": 0,
        "subject": "Action required: payment failed",
        "body": "Hi {{customer_name}}, your payment for {{plan_name}} failed." }'

Day 3: follow-up SMS

curl -X POST https://api.recurso.dev/v1/dunning-campaigns/{campaign_id}/steps \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "step_order": 2, "channel": "sms", "delay_hours": 72,
        "body": "Your {{plan_name}} payment is overdue." }'

Day 5: urgent email from a template

curl -X POST https://api.recurso.dev/v1/dunning-campaigns/{campaign_id}/steps \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "step_order": 3, "channel": "email", "delay_hours": 120,
        "template_name": "urgent_payment",
        "subject": "Urgent: service suspension soon" }'

Day 7: raise the payment wall

curl -X POST https://api.recurso.dev/v1/dunning-campaigns/{campaign_id}/steps \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{ "step_order": 4, "channel": "in_app", "delay_hours": 168,
        "is_payment_wall": true }'

Steps execute in step_order, escalating from a gentle reminder to a hard payment wall. If the invoice is paid at any point, the campaign stops immediately and any remaining steps are canceled:

Step Parameters

Parameter	Type	Required	Description
`step_order`	integer	Yes	Execution order within the campaign
`channel`	string	Yes	`email`, `sms`, or `in_app`
`delay_hours`	integer	Yes	Hours after the trigger event to fire
`template_name`	string	No	Name of a pre-configured message template
`subject`	string	No	Email subject line (email channel)
`body`	string	No	Message body content
`is_payment_wall`	boolean	No	Raise the payment wall at this step

Payment Wall

The payment wall blocks customer access until payment is resolved. Customers are redirected to a payment page instead of your application.

Check Payment Wall Status

curl https://api.recurso.dev/v1/invoices/{invoice_id}/payment-wall \
  -H "Authorization: Bearer $API_KEY"

{ "invoice_id": "…", "payment_wall_active": true }

Field	Type	Description
`payment_wall_active`	boolean	Whether the wall is currently blocking access
`grace_days_remaining`	integer	Days remaining before activation (0 if active)
`blocked_at`	string	Timestamp when activated (null if not active)
`invoice_id`	string	The overdue invoice triggering the wall

Manage Campaigns

List and Get Campaigns

curl -X GET https://api.recurso.dev/v1/dunning-campaigns \
  -H "Authorization: Bearer $API_KEY"

curl -X GET https://api.recurso.dev/v1/dunning-campaigns/dc_abc123 \
  -H "Authorization: Bearer $API_KEY"

Update Campaign and Steps

# Update the campaign (name / trigger_event)
curl -X PUT https://api.recurso.dev/v1/dunning-campaigns/{campaign_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Aggressive Recovery" }'

# Update a step — steps are addressed by their own id, not nested under the campaign
curl -X PUT https://api.recurso.dev/v1/dunning-campaigns/steps/{step_id} \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "delay_hours": 48, "body": "Updated SMS content" }'

curl -X DELETE https://api.recurso.dev/v1/dunning-campaigns/steps/{step_id} \
  -H "Authorization: Bearer $API_KEY"

Execution Tracking

Every step execution is logged with its status for monitoring and debugging.

Status	Description
`pending`	Step is scheduled and waiting to execute
`in_progress`	Step is currently being executed
`completed`	Step executed successfully
`failed`	Step execution failed (see error field)

Field	Type	Description
`id`	string	Unique execution ID
`campaign_id`	string	The parent campaign
`invoice_id`	string	The overdue invoice
`step_id`	string	The step that was executed
`status`	string	Execution status
`executed_at`	string	When the step was executed
`error`	string	Error message if status is `failed`

Recovered Revenue

Recurso attributes revenue back to the recovery machinery: whenever an invoice is paid after at least one failed payment attempt (or while an active dunning action or campaign was driving it), a recovery record is written with the amount, the number of attempts it took, the strategy that was in effect, and how many days the invoice took to recover.

Qualification — paid on the first try counts as nothing recovered; at least one failed attempt or an active dunning action/campaign must precede the payment
Strategy attribution — the tenant-wide retry strategy (DUNNING_STRATEGY, defaulting to the smart retry engine), or campaign when a dunning campaign execution was driving the invoice
Idempotent — one record per invoice, however many success paths fire

Query totals and a last-12-months series:

curl https://api.recurso.dev/v1/analytics/dunning/recovered \
  -H "Authorization: Bearer $API_KEY"

{
  "recovered_amount_total": { "INR": 1249750, "USD": 89900 },
  "recovered_count": 42,
  "avg_attempts": 2.4,
  "avg_days_to_recover": 3.7,
  "monthly": [
    { "month": "2026-06", "currency": "INR", "amount": 249950, "count": 8 },
    { "month": "2026-06", "currency": "USD", "amount": 19900, "count": 2 }
  ]
}

Amounts are in minor units, keyed by currency (never summed across currencies). The dunning dashboard renders the same data as a recovered revenue panel. See the API reference for details.

Recovered revenue is the number that justifies your dunning configuration: it is literally the money that would have churned without retries and campaigns.

Webhooks

Event	Description
`dunning.campaign_started`	A dunning campaign has begun for an invoice
`dunning.step_executed`	A campaign step was executed
`dunning.step_failed`	A campaign step failed to execute
`dunning.payment_wall_activated`	Payment wall was activated for a customer
`dunning.payment_wall_resolved`	Customer paid and the wall was removed
`dunning.campaign_completed`	Campaign ended (recovered or all steps exhausted)

Best Practices

Escalate Gradually

Start with a friendly email and escalate through SMS and payment wall over days, not hours.

Set a Default Campaign

Always have a default campaign so no failed payment goes unaddressed.

Use Templates

Use template IDs for consistent branding rather than inline body content.

Test Before Deploying

Create a non-default campaign first and test with internal invoices before making it the default.

What happens if a payment is recovered mid-campaign?

The campaign stops immediately. Pending steps are canceled and any active payment wall is deactivated automatically.

Can I run different campaigns for different plans?

Yes. Only one campaign can be the default, but you can assign specific campaigns to subscriptions or customer segments. The default is a fallback for invoices without an explicit assignment.

What template variables are available?

Available variables include {{customer_name}}, {{amount}}, {{currency}}, {{plan_name}}, {{invoice_id}}, {{payment_link}}, {{due_date}}, and {{grace_days_remaining}}.

Get Started

Migrate to Recurso

Core Concepts

Usage & Monetization

Money & Books

Tax & Compliance

Recover & Retain

Customer Portal

Platform & Integrations

Deploy & Operate

Reference

Automated Payment Recovery

Campaign Lifecycle

Create a Campaign

Campaign Parameters

Add Campaign Steps

Step Parameters

Payment Wall

Check Payment Wall Status

Manage Campaigns

List and Get Campaigns

Update Campaign and Steps

Execution Tracking

Recovered Revenue

Webhooks

Best Practices

Escalate Gradually

Set a Default Campaign

Use Templates

Test Before Deploying

​Automated Payment Recovery

​Campaign Lifecycle

​Create a Campaign

​Campaign Parameters

​Add Campaign Steps

​Step Parameters

​Payment Wall

​Check Payment Wall Status

​Manage Campaigns

​List and Get Campaigns

​Update Campaign and Steps

​Execution Tracking

​Recovered Revenue

​Webhooks

​Best Practices

Escalate Gradually

Set a Default Campaign

Use Templates

Test Before Deploying

Automated Payment Recovery

Campaign Lifecycle

Create a Campaign

Campaign Parameters

Add Campaign Steps

Step Parameters

Payment Wall

Check Payment Wall Status

Manage Campaigns

List and Get Campaigns

Update Campaign and Steps

Execution Tracking

Recovered Revenue

Webhooks

Best Practices