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
, seasonal
).
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 cyclemonthly
- payment method
123
and cycleannual
- payment method
456
and cyclemonthly
- payment method
456
and cycleannual
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.
Dunning Action Period | Authorized First | Payment Attempts (Hrs) | GracePeriod (Hrs) |
---|---|---|---|
Weekly | 1 | [72, 48, 24, 0] | 2 |
Monthly | 1 | [72, 48, 24, 0] | 2 |
3 Months | 1 | [72, 48, 24, 0] | 2 |
6 Months | 1 | [72, 48, 24, 0] | 2 |
Annual | 1 | [72, 48, 24, 0] | 2 |
Seasonal | 1 | [72, 48, 24, 0] | 2 |
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.
Payment Attempts (Hours) | Grace period | Payment attempts dates / timestamps: |
---|---|---|
[0] | 2 hours | 13:05; 14:05; 15:05 |
[0,-1,-3,-5] | 5 hours | 13:05; 14:05; 16:05; 18:05 |
[0,-1,-3,-5] | 7 hours | 13:05; 14:05; 16:05; 18:05; 19:05; 20:05 |
[0,-1,-3,-5] | 1 hour | 13:05; 14:05; 16:05; 18:05 |
Good to know
Subscriptions are shown as active in the ChurnIQ dashboard when they are in a grace period.
Updated 2 months ago