Dunning Action Settings

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

Please note that apart from subscriptions (recurring payments), you should also set up dunning actions settings for passes.

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, you would have to create settings 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

📘

This minimal configuration will suffice, but we strongly suggest creating dunning action settings for all the supported cycle durations, as it is easy to forget to create this setting when a subscription with a previously unsupported cycle is added.

❗️

Important for PayPal

Dunning actions settings for PayPal payment method require the authorizedFirst property to be set to true.

Recommended Dunning Settings

If you are not going for custom dunning actions settings, please use our recommended dunning actions settings for the respective billing cycles.

If your offers include passes only, you can set the grace period to 0 hours.

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.

Note:
Grace period also applies if a customer has cancelled their subscription. Then it gives an additional time to restore a canceled subscription before it terminates.

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 Cleeng is NOT your Merchant of Record.

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.

Grace Period ≤ Payment Attempts

If a grace period is shorter than the period for which payment attempts are set or it equals zero -> only payment attempts settings are followed.

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

Example:

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

📘

Good to know

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