Dunning

Dunning is the policy your account uses to retry failed subscription payments and recover revenue. The Python SDK exposes two surfaces:

client.dunning_config — the single, account-wide retry/recovery policy.
client.revenue_recovery_automations — per-event automations layered on top.

`client.dunning_config`

There is exactly one dunning config per account. The first call to create_or_replace initializes it; subsequent calls overwrite.

`create_or_replace`

config = client.dunning_config.create_or_replace(
    retry_schedule=[1, 3, 7, 14],          # days after failure to retry
    final_action="cancel",                 # or "mark_uncollectible"
    send_customer_emails=True,
    idempotency_key="dunning-2026-q2",
)

Returns: DunningConfig. All fields are accepted via **kwargs.

`retrieve`

config = client.dunning_config.retrieve()

`update`

config = client.dunning_config.update(send_customer_emails=False)

PATCH semantics — only the fields you pass are changed.

`client.revenue_recovery_automations`

Automations run alongside (or instead of) the built-in retry schedule — e.g. "on second failure, send a custom email and create a follow-up task."

`list`

automations = client.revenue_recovery_automations.list()

Returns list[RevenueRecoveryAutomation].

`create`

automation = client.revenue_recovery_automations.create(
    name="Notify CSM on second failure",
    trigger="payment_failed",
    conditions={"attempt": 2},
    actions=[{"type": "webhook", "url": "https://example.com/csm-alert"}],
    idempotency_key="auto-csm-alert-v1",
)

`update`

client.revenue_recovery_automations.update("auto_123", enabled=False)

`delete`

client.revenue_recovery_automations.delete("auto_123")

`list_runs`

runs = client.revenue_recovery_automations.list_runs("auto_123")
for r in runs:
    print(r.id, r.status, r.created_at)

Returns list[RevenueRecoveryAutomationRun].

Object shape

DunningConfig mirrors the configured policy. Common fields:

Field	Notes
`retry_schedule`	List of day offsets, e.g. `[1, 3, 7, 14]`.
`final_action`	What to do once retries exhaust.
`send_customer_emails`	Whether to email the customer.

RevenueRecoveryAutomation and RevenueRecoveryAutomationRun carry id, status, created_at, plus the per-trigger configuration.

Examples

Replace a stale dunning policy

client.dunning_config.create_or_replace(
    retry_schedule=[1, 3, 5],
    final_action="cancel",
    send_customer_emails=True,
    idempotency_key="dunning-2026-q3-rev1",
)

Audit recent automation runs

for auto in client.revenue_recovery_automations.list():
    runs = client.revenue_recovery_automations.list_runs(auto.id)
    failed = [r for r in runs if (r.status or "").lower() == "failed"]
    if failed:
        log.warning("automation %s has %d failed runs", auto.id, len(failed))

React to recovery in your webhook handler

if event.type == "revenue_recovery.action_completed":
    log.info("recovery action ran: %s", event.data)

Dunning

On this page