Recurring Schedules
Status: Roadmap. The conceptual model is documented here. Public REST endpoints described below are not yet wired into the API router (no handler is registered for these paths). The page describes the planned shape; treat any code samples as illustrative pending implementation.
A recurring schedule is a cron-style trigger that fires a chosen action on a repeating cadence. Unlike scheduled changes (one-off, future, entity-bound), a recurring schedule keeps firing on its cron expression until you pause or delete it.
Why this matters. Billing operations live and die by repeatable, auditable automation - manual quarterly settlement runs and ad-hoc cron scripts are where reconciliation pain accumulates and where outages tend to start. Kontorion's recurring schedules let you express any repeating billing action as a cron expression with timezone awareness, action configuration, and run history, replacing scattered scripts with a single managed surface that finance and operations can both inspect. The same model supports a monthly partner settlement run, a weekly customer usage summary email, a quarterly automatic plan-version publication, and a daily reconciliation export to a downstream ledger.
When to use
- Generate a monthly settlement run for a partner
- Email a usage summary to customers every Monday
- Auto-publish a queued plan version on the 1st of each quarter
- Run a periodic reconciliation report against an external ledger
For a one-off future action, use scheduled changes. For an unbounded retry sequence after a failure, use dunning.
Anatomy
| Field | Description |
|---|---|
name | Human-readable label |
cron | Standard 5-field cron expression (minute hour day-of-month month day-of-week) |
timezone | IANA timezone name (Europe/Berlin, America/New_York); the cron is interpreted in this zone |
action_type | generate_settlement, email_report, publish_plan_version, webhook_trigger, etc. |
action_config | Per-action payload (counterparty ID, report template, target plan version) |
status | active, paused |
next_run_at | When the schedule will fire next (computed from cron + timezone) |
last_run_at / last_run_status | Audit fields |
Creating a schedule
Code
Common patterns
| Cadence | Cron |
|---|---|
| Every day at 06:00 | 0 6 * * * |
| Every Monday at 09:00 | 0 9 * * 1 |
| 1st of each month at midnight | 0 0 1 * * |
| Last day of each quarter | 0 0 L 3,6,9,12 * |
| Every 15 minutes | */15 * * * * |
Action types
| Action | Behavior |
|---|---|
generate_settlement | Trigger a settlement run for the configured counterparty + period |
email_report | Render a templated report and email it to configured recipients |
publish_plan_version | Publish a draft plan version (typically used for staged rollouts) |
migrate_subscribers | Run a plan migration cohort |
webhook_trigger | Fire a webhook payload of your choice (catch-all for custom flows) |
Pausing and resuming
Code
Pausing freezes next_run_at; resuming recomputes it from the current time forward.
Failure handling
If a run fails, the failure is logged on the schedule's run history and the next run still fires on schedule (failures don't push subsequent runs back). For action types that benefit from retries (e.g., generating a settlement), the action itself owns the retry logic - the schedule just kicks it off.
Run history
Code
Returns the last N runs with timestamps, durations, status, and any output artifact references (e.g., the generated settlement ID).
Next steps
- Scheduled Changes - for one-off future actions
- Settlements - the most common action target
- API Reference - Recurring Schedules