Skip to navigation

Update Dunning Settings

View as Markdown
Update dunning settings for an account.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

account_idstringRequired

Request

This endpoint expects an object.
enable_retriesboolean or nullOptional
Enable automatic failed payment recovery retries
enable_emailsboolean or nullOptional
Enable automatic failed payment recovery emails
enable_outcome_emailsboolean or nullOptional

Enable end-of-dunning outcome emails (subscription paused/canceled/left active). When unset, these follow the enable_emails toggle.

contact_infoobject or nullOptional
Contact information for dunning emails
subscription_status_on_failureenum or nullOptional

What to do with subscription if all payment attempts fail. Options: ‘cancel’ (default) or ‘leave_active’

Allowed values:
invoice_status_on_failureenum or nullOptional

What to do with invoice if all payment attempts fail. Options: ‘mark_uncollectible’ (default), ‘leave_open’, or ‘void’

Allowed values:
excluded_product_idslist of strings or nullOptional

Product IDs to exclude from dunning (empty or unset = dun all)

settle_past_due_on_pm_updateboolean or nullOptional

When a customer updates their payment method, immediately charge all past-due invoices. Invoices not yet due are not affected.

update_renewal_on_overdue_paidboolean or nullOptional
Update subscription renewal date when overdue invoices are paid
enable_incomplete_subscription_dunningboolean or nullOptional

Retry the failed initial charge on incomplete subscriptions created outside of checkout (including via the dashboard or direct API calls). Subscriptions created through checkout are never dunned.

enable_unpaid_invoice_remindersboolean or nullOptional

Enable reminder emails for unpaid invoices customers pay by link (send_invoice). Does not apply to automatically charged invoices.

unpaid_invoice_reminder_due_soon_enabledboolean or nullOptional
Send the 'invoice due soon' reminder before the due date.
unpaid_invoice_reminder_due_soon_daysinteger or nullOptional1-14

Days before the due date to send the ‘invoice due soon’ reminder (1-14).

unpaid_invoice_reminder_due_today_enabledboolean or nullOptional
Send the 'invoice due today' reminder on the due date.
unpaid_invoice_reminder_overdue_enabledboolean or nullOptional
Send the 'invoice overdue' reminder after the due date.
unpaid_invoice_reminder_overdue_daysinteger or nullOptional1-60

Days after the due date to send the ‘invoice overdue’ reminder (1-60).

unpaid_invoice_failure_handling_daysinteger or nullOptional0-60

Days after an unpaid invoice’s due date before failure handling applies (0-60). Applies to send_invoice invoices only.

Response

Successful Response
enable_retriesboolean or nullOptionalDefaults to false

Enable automatic failed payment recovery retries. Defaults to False: an account that never configures dunning does not retry failed payments.

enable_emailsboolean or nullOptionalDefaults to false

Enable automatic failed payment recovery (in-cycle retry) emails. Requires enable_retries: with retries off there is no retry cycle, so these are not sent (end-of-dunning outcome emails are separate — see enable_outcome_emails). Defaults to False: an account that never configures dunning sends no dunning emails.

enable_outcome_emailsboolean or nullOptional

Enable end-of-dunning outcome emails (subscription paused/canceled/left active). When unset (null), these follow the enable_emails toggle, preserving prior behavior; set explicitly to control them independently.

contact_infoobject or nullOptional
Contact information for dunning emails
subscription_status_on_failurestring or nullOptional

What to do with subscription if all payment attempts fail. Options: ‘cancel’ (default) or ‘leave_active’

invoice_status_on_failurestring or nullOptional

What to do with invoice if all payment attempts fail. Options: ‘mark_uncollectible’ (default), ‘leave_open’, or ‘void’

excluded_product_idslist of strings or nullOptional

Product IDs to exclude from dunning: an invoice is not dunned when every product on it is excluded (empty or unset means every product is dunned).

settle_past_due_on_pm_updateboolean or nullOptionalDefaults to true

When a customer updates their payment method, immediately charge all past-due invoices. Invoices not yet due are not affected.

update_renewal_on_overdue_paidboolean or nullOptionalDefaults to true
Update subscription renewal date when overdue invoices are paid
enable_incomplete_subscription_dunningboolean or nullOptionalDefaults to false

Retry the failed initial charge on incomplete subscriptions created outside of checkout (including via the dashboard or direct API calls). Requires enable_retries: with retries off the initial charge is not dunned. Defaults to False. Subscriptions created through checkout are never dunned.

enable_unpaid_invoice_remindersboolean or nullOptionalDefaults to false

Enable reminder emails for unpaid invoices customers pay by link (send_invoice). Defaults to False: an account that never configures reminders sends none. Does not apply to automatically charged invoices.

unpaid_invoice_reminder_due_soon_enabledboolean or nullOptionalDefaults to true
Send the 'invoice due soon' reminder before the due date.
unpaid_invoice_reminder_due_soon_daysinteger or nullOptionalDefaults to 3

Days before the due date to send the ‘invoice due soon’ reminder (1-14).

unpaid_invoice_reminder_due_today_enabledboolean or nullOptionalDefaults to true
Send the 'invoice due today' reminder on the due date.
unpaid_invoice_reminder_overdue_enabledboolean or nullOptionalDefaults to true
Send the 'invoice overdue' reminder after the due date.
unpaid_invoice_reminder_overdue_daysinteger or nullOptionalDefaults to 1

Days after the due date to send the ‘invoice overdue’ reminder (1-60).

unpaid_invoice_failure_handling_daysinteger or nullOptionalDefaults to 14

Days after an unpaid invoice’s due date before failure handling applies (0-60). Applies to send_invoice invoices only; automatically charged invoices are unaffected.

Errors

422
Unprocessable Entity Error