Update Dunning Settings

PATCH

/api/accounts/:account_id/dunning-settings

PATCH

/api/accounts/:account_id/dunning-settings

curl -X PATCH https://app.paymentkit.com/api/accounts/account_id/dunning-settings \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "enable_retries": true,
  "enable_emails": true,
  "enable_outcome_emails": true,
  "contact_info": {
    "from_email": "billing@example.com",
    "reply_to_email": "support@example.com",
    "email_signature_title": "Billing Department",
    "email_signature_name": "John Smith",
    "cc_recipients": [
      "cc1@merchant.com",
      "cc2@merchant.com"
    ],
    "bcc_recipients": [
      "bcc1@merchant.com",
      "bcc2@merchant.com"
    ]
  },
  "subscription_status_on_failure": "cancel",
  "invoice_status_on_failure": "mark_uncollectible",
  "apply_to_product_ids": [
    "prod_abc123",
    "prod_def456"
  ],
  "settle_past_due_on_pm_update": true,
  "update_renewal_on_overdue_paid": true,
  "enable_incomplete_subscription_dunning": true
}

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:

apply_to_product_idslist of strings or nullOptional

List of product IDs to apply dunning to

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.

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 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'

apply_to_product_idslist of strings or nullOptional

List of product IDs to apply dunning to (empty means all products)

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). Defaults to False. Subscriptions created through checkout are never dunned.

Errors

422

Unprocessable Entity Error