Skip to content

Dunning ​

Dunning is TiruPay's escalation process for orders that fall overdue - both invoice-style orders waiting on a bank transfer and subscription/PAYG orders whose mandate charge failed. Once an order is revoked for non-payment, a service-configured dunning policy determines how many reminder notices go out, at what intervals, with what fees, and what happens once the policy is exhausted.

Dunning is entirely opt-in per service: a service with no policy (or an inactive one) is never automatically escalated - its overdue orders simply sit in REVOKED/DUNNING until you intervene manually.

Concepts ​

DunningPolicy ​

One per service (optional). It has:

  • is_active - whether automatic escalation currently applies. An inactive policy is treated identically to having no policy at all.
  • a tier ladder - an ordered chain of DunningTier rows.

DunningTier ​

A single step in the ladder, identified by tier_order (1-10, unique within the policy). Each tier defines:

  • delay_days - how many days after the previous tier fired before this one fires. For the first tier (tier_order = 1), this is measured from when the order was revoked (due_date + the payment method's grace_period_days - see Payment Method Configuration), not cumulatively from the order's original due date. Editing one tier's delay_days never requires recalculating the tiers after it.
  • one or more DunningTierFee rows - optional. A tier with none charges no fee when it fires.

A tier can be free

Sending a reminder without charging anything is a valid, common choice - just leave fees empty for that tier.

DunningTierFee ​

A tier's per-currency fee, since fees are always tracked per-currency, never in a single fixed currency:

  • currency_code - the currency this fee applies to.
  • fee_amount - the amount charged, in currency_code, when this tier fires for an order in that currency. May be 0.

If a tier has no fee row for an order's currency, that order simply isn't charged when the tier fires - the reminder is still sent.

Dunning fees are VAT-free

Dunning fees are treated as damages for late payment, not a taxable supply - no tax is calculated or charged on them, regardless of the order's country or the customer's tax status.

DunningNotice ​

An immutable record of a single reminder sent for an order - one row created every time a tier fires. Tracks:

  • round_number - 1-based, purely sequential per order. Distinct from the firing tier's tier_order: if the policy is edited between rounds, the two can diverge.
  • previous_notice_id - links to the prior notice in this order's escalation chain, so the full history can be walked without relying on timestamps.
  • fee_position_id - the order position created for this round's fee, if the firing tier charged one.
  • ext_invoice_id and reminder_deadline - the external dunning document ID and the deadline that was set for the next reminder when this notice was sent.

How Escalation Works ​

Once an order is REVOKED or DUNNING with a next_dunning_date in the past, TiruPay determines the next tier to fire:

  1. If the order has no prior DunningNotice, the lowest-tier_order tier fires.
  2. Otherwise, TiruPay finds the first tier (by ascending tier_order) that hasn't fired for this order yet.
  3. If every tier has already fired, the order is written off instead (see below) - no further reminder is sent.
plain
Order revoked (REVOKED, due_date + grace_period_days passed)
  ↓
Tier 1 fires → dunning notice sent, fee charged (if configured) → DUNNING
  ↓ [delay_days of tier 2 later]
Tier 2 fires → dunning notice sent, fee charged (if configured)
  ↓ [delay_days of tier 3 later]
  ...
  ↓ [no tier left]
Order written off → WRITTEN_OFF

When a tier fires:

  1. A dunning notice is created at the invoicing provider, referencing the order's active invoice.
  2. If the tier has a fee configured for the order's currency, a new order position is added for it (position_type: dunning_fee) - unless this round's fee was already recorded (idempotent against retries). Fee positions accumulate: every prior round's fee stays on the order, so the order's total always reflects everything charged across the whole dunning history.
  3. A DunningNotice is recorded, chained to the previous one.
  4. next_dunning_date is set to when the next tier should fire (or to the provider's own reminder deadline, if it returns one - see Provider Support below).
  5. The order status becomes DUNNING.

Write-off ​

When an order has fired every tier in its policy and comes due again, TiruPay writes it off instead of sending another reminder:

  1. Any PAYG usage billed on the order is marked as never to be collected through it again.
  2. If the order belongs to a subscription that is currently paused, the subscription is terminated.
  3. The order status becomes WRITTEN_OFF - terminal, with no automatic way back.
  4. An admin notification is sent so the debt can be handed to a manual collection process - TiruPay has no collections-agency integration today, so this notification is the current end of the line.

Write-off Does Not Restore Access

The external invoice is not cancelled at write-off time - it remains the accounting record of the receivable (see below for what happens if it's paid afterwards). Any balance freeze blocking further usage due to the overdue payment is not lifted either - write-off is an automatic decision with no human judgment behind it, so it deliberately does not restore the customer's access. Restoring access requires a deliberate, separate admin action.

Late Payment After Write-off ​

If a payment nonetheless arrives for a WRITTEN_OFF order, TiruPay does not auto-complete it - unlike a payment arriving for a REVOKED/DUNNING order, which is reconciled automatically. Instead, an admin is notified and must complete the order manually. This is deliberate: a write-off is a considered decision to stop collecting, so a late payment shouldn't silently reopen it without review.

The external invoice is still booked as paid in the invoicing provider, though - money did arrive, and there's no reason to leave the accounting record showing "open" while the admin decides how to handle the rest.

Configuring a Policy ​

POST /dunning/policy creates a service's policy, optionally with its initial tier ladder in one call:

json
{
  "is_active": true,
  "tiers": [
    {
      "tier_order": 1,
      "delay_days": 7,
      "fees": [{ "currency_code": "EUR", "fee_amount": "5.00" }]
    },
    {
      "tier_order": 2,
      "delay_days": 7,
      "fees": [{ "currency_code": "EUR", "fee_amount": "5.00" }]
    }
  ]
}

GET /dunning/policy fetches the policy including its full tier ladder. PATCH /dunning/policy replaces the tier ladder atomically when tiers is provided - existing tiers are matched and updated by tier_order; any tier_order no longer present in the new list is removed.

Limits

A policy may have at most 10 tiers. tier_order values must be unique within a policy, and a tier's fee currency_code values must be unique within that tier.

There is no customer-facing access to dunning policy configuration - only Service and Admin roles can view or manage it.

Good to know ​

Dunning Applies to Both Overdue Paths Uniformly

The same policy governs invoice-style orders (waiting on a bank transfer) and mandate-based orders (subscription renewal or PAYG charge failures) - dunning is a bookkeeping decision of the service, not a property of the payment method. See Order Lifecycle for how each path reaches REVOKED in the first place.

FAILED Orders Are Never Dunned

OrderStatus.FAILED orders (a technical/infrastructure error, not the customer's fault) are retried automatically and never enter dunning, never get charged a fee, and are unaffected by a service's dunning policy.

Relationships ​

  • Orders - Dunning fees are added as order positions; escalation only applies to REVOKED/DUNNING orders.
  • Order Lifecycle - Describes how an order reaches REVOKED in the first place, and the WRITTEN_OFF terminal status.
  • Payments - ServicePaymentMethodConfig.grace_period_days determines when an overdue order is revoked and dunning begins.
  • Invoicing - Dunning notices are created through the same invoicing provider used for invoices and credit notes.
  • Subscriptions - A paused subscription is terminated when its order is written off.
  • PAYG - Usage billed on a written-off order is never collected through that order again.
  • Notifications - Admins are notified on write-off, and again if a payment arrives for an already-written-off order.