Dunning Action Settings

🚧

Important

Dunning action settings are configured automatically by Cleeng when creating a new payment method.

  • If you use Cleeng Merchant, Dunning actions settings configured by Cleeng should remain default values, except otherwise agreed with your account manager.
  • If you operate for the web the Merchant of Record (hence, when you do NOT use Merchant), dunning actions settings are allowed to be adjusted.

You can check the setup of your dunning actions easily by visiting the Cleeng Dashboard -> Admin -> Dunning Actions. See this article for more details.

Dunning is the process of retrying payment attempts and sending payment reminders to customers when a payment gets rejected. With Cleeng you can configure payment retries at intervals to ensure payment will be recovered and subscription can continue its cycles.

Dunning actions settings specify when Cleeng should emit the events mentioned in the Webhooks section. They are set up automatically for all all your payment method Ids and all subscription cycle durations (weekly, monthly, 3-months, 6-months, annual, seasonal).

If you operate for the web the Merchant of Record (hence, when you do NOT use Merchant), dunning actions settings are allowed to be adjusted and you can set them up by calling this endpoint.

Example:
Let’s imagine you have 2 payment methods 123 and 456. You offer your subscribers 2 types of subscriptionsmonthly and annual. In this case, dunning actions are set up for the following method-cycle combinations:

  • payment method 123 and cycle monthly
  • payment method 123 and cycle annual
  • payment method 456 and cycle monthly
  • payment method 456 and cycle annual

❗️

Important

Dunning actions settings for PayPal and Adyen payment methods require the authorizedFirst property to be set to true.

Default Dunning Settings

Dunning Settings presented below are default settings that are created automatically when creating a new payment method.

Dunning Action PeriodAuthorized First*Payment Attempts (Hrs)GracePeriod (Hrs)
Monthly1[0, -24, -72, -168, -359]360
3 Months1[0, -24, -72, -168, -359]360
6 Months1[0, -24, -72, -168, -359]360
Annual1[0, -24, -72, -168, -359]360
Seasonal1[0, -24, -72, -168, -359]360

*Authorized First value depends on the payment gateway. Here we have default Authorized First values for PayPal and Adyen, but they might be different for other payment gateways.

Please note that Payment Attempts values should be negative (below zero) if you want dunning actions to take place at certain intervals during the grace period.

🚧

Important

Grace period should be set to maximum 2 hours after the last payment attempt.

For example, if you set the last payment attempt to [0], then the grace period length should be set from 0 to 2 hours. If you set the last payment attempt to [-46], the maximum grace period is 48 hours.

Payment Attempts and Grace Period

You can set both payment attempts and a grace period for a subscription, however payment attempts settings have priority over a grace period. Please see below for different scenarios, depending on a possible setup.

🚧

Note

Dunning actions settings can be adjusted only if you do NOT use Merchant.

No Payment Attempts during Grace Period

If there are no payment attempts set during a defined grace period -> payment retries are made every hour during the grace period.

Payment Attempts = Grace Period

If payment attempts are set for the same length of time as the grace period -> payment retries are made as defined for payment attempts frequency.

For example, if payment attempts are defined as [0,-1,-3,-5] and the grace period is set to 5 hours, payment retries are made as per payment attempts settings (there will be 4 payment attempts).

Grace Period > Payment Attempts

If a grace period is longer than the period for which payment attempts are set -> payment attempts settings are followed for as long as they are set. After that time, the rules for grace period are followed and payment retries are made every hour until the end of the grace period.

For example, if payment attempts are defined as [0,-1,-3,-5] and the grace period is set to 7 hours, at first payment retries are made as defined for payment attempts frequency (there will be 4 payment attempts) and then for each hour that is later than the last defined payment attempt, an additional payment retry is made.

Example:

See this example to illustrate a case when an original next payment date for a subscription is: 4 Oct 2022, at 13:05.

Payment Attempts (Hours)Grace periodPayment attempts dates / timestamps:
[0]2 hours13:05; 14:05; 15:05
[0,-1,-3,-5]5 hours13:05; 14:05; 16:05; 18:05
[0,-1,-3,-5]7 hours13:05; 14:05; 16:05; 18:05; 19:05; 20:05

📘

Good to know

Subscriptions are shown as active in the ChurnIQ dashboard when they are in a grace period.