Skip to main content

Create a dunning rule

POST 
/subscriptions/dunning-rules

Dunning rules must use a fixed strategy. This means payments are retried on a fixed schedule.

When an invoice is created, it immediately becomes eligible for payment by the next payment run. If the first payment attempt fails then the invoice enters dunning. In subsequent payment runs, invoices are only considered for payment if they meet the dunning rules you create.

You can configure a dunning rule to be the default for your store. There can only be one default rule per store. All invoices in your store will then perform dunning according to the specified rules.

note

If no dunning rule is configured, then payment is retried once a day for 10 days, in total 11 payments. You can decide what action to take after the Subscriptions has stopped retrying the payments.

The following attributes are used to define a fixed schedule:

  • `payment_retry_unit - the unit of time used to measure the intervals between payment attempts or retries.
  • payment_retry_interval - the number of payment_interval-units to wait between each payment retry attempt.
  • payment_retries_limit - the number of times subscriptions attempts payments retries before an action is taken.
  • action - the action to take if payment is not successful.

For example, if:

  • the payment_retry_unit is days
  • the payment_retry_interval is 2
  • the payment_rety_limit is 10
  • the action is close.

Subscriptions attempts to retry the payment every 2 days until 10 payment attempts have been tried. At that point, the subscription ends and it's status changes to inacive.

Following on from this, you can specify that the dunning rule is no longer the default. You do not have to specify another rule to replace it. If you do remove the default dunning rule, the store defaults to the behavior that is followed when dunning is not enabled.

Request​

Body

    data DunningRuleCreaterequired
    type SubscriptionDunningRuleType (string)required

    Possible values: [subscription_dunning_rule]

    attributes DunningRuleAttributesrequired

    The dunning rule attributes you can use to configure your payment retry strategy.

    payment_retry_type stringrequired

    Possible values: [fixed, backoff, tiered]

    The strategy used to make payments. Always fixed. This means payments are retried on a fixed schedule as defined by the payment_retry_unit and payment_retry_interval, for example, every two days.

    payment_retry_interval int64

    Possible values: >= 1 and <= 1024

    The number of payment_interval_units to wait between each payment retry attempt.

    payment_retry_unit string

    Possible values: [day, week]

    The unit of time used to measure the intervals between payment attempts or retries.

    payment_retry_multiplier double

    Possible values: >= 1 and <= 1024

    The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.

    payment_retries_limit int64required

    The number of times Subscriptions attempts payment retries before action is taken.

    action stringrequired

    Possible values: [none, pause, close, suspend]

    The action to take after all payment attempts for an invoice have failed.

    • None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.
    • Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.
    • close a subscription. The subscription ends and it's status becomes inactive. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.
    default boolean

    Set to true if you want this rule to be the default for the store.

Responses​

Success. The dunning rule set is created.

Schema
    data DunningRule
    id UUID (string)

    The unique identifier.

    type SubscriptionDunningRuleType (string)required

    Possible values: [subscription_dunning_rule]

    attributes DunningRuleAttributesrequired

    The dunning rule attributes you can use to configure your payment retry strategy.

    payment_retry_type stringrequired

    Possible values: [fixed, backoff, tiered]

    The strategy used to make payments. Always fixed. This means payments are retried on a fixed schedule as defined by the payment_retry_unit and payment_retry_interval, for example, every two days.

    payment_retry_interval int64

    Possible values: >= 1 and <= 1024

    The number of payment_interval_units to wait between each payment retry attempt.

    payment_retry_unit string

    Possible values: [day, week]

    The unit of time used to measure the intervals between payment attempts or retries.

    payment_retry_multiplier double

    Possible values: >= 1 and <= 1024

    The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.

    payment_retries_limit int64required

    The number of times Subscriptions attempts payment retries before action is taken.

    action stringrequired

    Possible values: [none, pause, close, suspend]

    The action to take after all payment attempts for an invoice have failed.

    • None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.
    • Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.
    • close a subscription. The subscription ends and it's status becomes inactive. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.
    default boolean

    Set to true if you want this rule to be the default for the store.

    meta DunningRuleMetarequired
    owner stringrequired

    The owner of a resource, either store or organization.

    timestamps Timestampsrequired
    updated_at stringrequired

    The date and time a resource was updated.

    created_at stringrequired

    The date and time a resource was created.

Loading...