Dunning & Payment Recovery

# Dunning is configured as a campaign of timed steps, not a settings blob.
# 1. Create the campaign:
curl -X POST https://api.recurso.dev/v1/dunning-campaigns \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Standard dunning", "trigger_event": "payment_failed" }'

# 2. Add steps (delay_hours from the trigger; channel email|sms|in_app):
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": 24,
        "subject": "Payment failed — action needed",
        "body": "Hi {{customer_name}}, your payment for {{plan_name}} failed." }'
# Later steps can set "is_payment_wall": true to gate access.

Subject: Action Required: Payment Failed

Hi {CustomerName},

We couldn't process your payment for {InvoiceNumber}.

Amount: {Amount}
Due Date: {DueDate}

Please update your payment method to avoid service interruption.

[Update Payment Method]
[Pay Now]

Subject: ⚠️ Payment Still Pending

Your payment of {Amount} is still outstanding.

We'll attempt to charge your card again on {NextRetryDate}.

To avoid service interruption on {SuspensionDate}:
[Update Payment Method]

Subject: 🚨 Final Notice: Service Suspension

This is your final notice before service suspension.

If we don't receive payment by {SuspensionDate}, your subscription will be suspended.

[Pay Now to Keep Access]

{
  allow_customer_retry: true,
  retry_url: '{portal}/pay/{invoice_id}'
}

const metrics = await recurso.analytics.dunning({
  period: 'last_30_days'
});

// Returns
{
  invoices_entered: 45,
  recovered: 38,
  recovery_rate: 84.4,
  uncollectible: 7,
  average_days_to_recovery: 2.3
}