Payment dunning sequence writer

Overview

The dunning writer ingests a JSON recipe that defines up to five escalation stages. Each stage specifies a delay, an email template ID, and an optional webhook URL for external side effects. Meridian evaluates the recipe against live subscription state and emits scheduled jobs into the task queue.

Recipe schema

{
  "name": "default-dunning",
  "stages": [
    { "delay_hours": 24,  "template": "payment_failed" },
    { "delay_hours": 72,  "template": "payment_second_notice" },
    { "delay_hours": 168, "template": "payment_final",
      "webhook": "https://api.example.com/suspend" }
  ]
}

Execution model

• 1.Invoice transitions to past_due
• 2.Writer loads the active recipe for the tenant
• 3.Stage-0 job is enqueued with a delay matching the first tier
• 4.On each tick the worker sends the templated email and fires the optional webhook
• 5.If payment is captured mid-sequence the pipeline halts immediately

Webhook contract

Webhooks receive a signed POST with the subscription ID, customer email, current stage index, and a reason code. The endpoint must return 200 within 5 seconds. Non-2xx responses are retried with exponential backoff capped at three attempts.

Idempotency

Every stage carries a deterministic idempotency key derived from the subscription ID and stage index. Duplicate deliveries are suppressed at the queue layer.