Dunning

Dunning is the recovery flow that runs when an invoice or subscription payment fails — retry schedules, reminder emails, and recovery automations. The SDK exposes two related resources:

client.dunning_config — the singleton config that controls retry behaviour and customer-facing emails.
client.revenue_recovery_automations — programmable rules that fire in response to recovery events (e.g. "if invoice still unpaid after 7 days, cancel the subscription").

Dunning config

A single config per merchant. create_or_replace POSTs the full config; update PATCHes the fields you pass; retrieve reads the current state.

`client.dunning_config.create_or_replace(**body)`

POST /dunning-config.

client.dunning_config.create_or_replace(
  retry_mode:           "smart",
  smart_retry_attempts: 4,
  payment_failed_email_enabled: true
)

`client.dunning_config.retrieve`

GET /dunning-config.

`client.dunning_config.update(**body)`

PATCH /dunning-config.

client.dunning_config.update(payment_failed_email_enabled: false)

Revenue recovery automations

Rule-based actions that fire on recovery events. Each rule has a trigger_type: and an action body the API interprets.

`client.revenue_recovery_automations.list`

GET /revenue-recovery-automations.

`client.revenue_recovery_automations.create(**body)`

POST /revenue-recovery-automations.

client.revenue_recovery_automations.create(
  trigger_type: "invoice_overdue",
  conditions:   { days_overdue: 7 },
  actions:      [{ type: "cancel_subscription" }]
)

`client.revenue_recovery_automations.update(id, **body)`

PATCH /revenue-recovery-automations/:id.

client.revenue_recovery_automations.update("auto_…", active: false)

`client.revenue_recovery_automations.delete(id)`

DELETE /revenue-recovery-automations/:id.

`client.revenue_recovery_automations.runs(id)`

GET /revenue-recovery-automations/:id/runs. Audit trail of every time this automation fired.

client.revenue_recovery_automations.runs("auto_…")

Object shapes

DunningConfig — :retry_mode (smart | manual | off), :smart_retry_attempts, :retry_schedule, :payment_failed_email_enabled, :reminder_emails, …

RevenueRecoveryAutomation — :id, :trigger_type, :conditions, :actions, :active, :created_at, …

Webhook events

Subscribe to invoice.payment_failed to react when dunning starts and revenue_recovery.action_completed when an automation runs.

Examples

Tighten dunning policy

client.dunning_config.update(retry_mode: "smart", smart_retry_attempts: 6)

Auto-cancel after a week of failed retries

client.revenue_recovery_automations.create(
  trigger_type: "invoice_overdue",
  conditions:   { days_overdue: 7 },
  actions:      [{ type: "cancel_subscription", at_period_end: false }]
)

Dunning

On this page