Scheduled Runs

A schedule runs bill runs automatically — either recurring (daily / weekly / monthly) or one-time at a future date. It is a thin wrapper over a BillingRunJob JobInstance and its timer; you manage a schedule, not the job plumbing.

POST /api/v1/billingRunSchedules and friends.

Cadence model — repeats

repeats	Behaviour
NONE	One-time run — "schedule it before running it". Fires exactly once at startDate. After it fires, the schedule reports status: COMPLETED.
DAILY / WEEKLY / MONTHLY	Recurring — the 7-field cron spec drives the timer. status is ACTIVE or PAUSED.

The New Bill Run form's cadence selector maps directly: Run once at… → repeats: NONE, Recurring → repeats: MONTHLY (adjust in the schedule form).

Endpoints

Endpoint	Purpose
POST /api/v1/billingRunSchedules	Create a schedule (a TimerEntity + a BillingRunJob JobInstance).
GET /api/v1/billingRunSchedules	List all schedules.
GET /api/v1/billingRunSchedules/{code}	One schedule.
PUT /api/v1/billingRunSchedules/{code}	Update cron / cycles / options.
DELETE /api/v1/billingRunSchedules/{code}	Delete the schedule.
POST /api/v1/billingRunSchedules/{code}/pause	Pause a recurring schedule (no future firings).
POST /api/v1/billingRunSchedules/{code}/resume	Resume a paused schedule.
POST /api/v1/billingRunSchedules/{code}/runNow	Fire the schedule's job immediately, regardless of its timer.

Create payload

{
  "name": "Monthly_B2C_Run",
  "repeats": "MONTHLY",
  "cron": {
    "second": "0", "minute": "0", "hour": "2",
    "dayOfMonth": "1", "month": "*", "dayOfWeek": "*", "year": "*"
  },
  "billingCycleCodes": ["Monthly_B2C"],
  "processType": "AUTOMATIC",
  "rejectAutoAction": "MOVE",
  "suspectAutoAction": "MOVE",
  "generateAO": true,
  "active": true
}

One-time example:

{
  "name": "Catchup_2026_06_01",
  "repeats": "NONE",
  "startDate": "2026-06-01T02:00:00Z",
  "billingCycleCodes": ["Monthly_B2C"],
  "processType": "FULL_AUTOMATIC"
}

Field	Type	Notes
name	string	required — becomes the schedule code
repeats	enum	NONE / DAILY / WEEKLY / MONTHLY
cron	object	7 calendar fields; required for recurring cadences
startDate	ISO-8601	one-time: the exact fire datetime; recurring: range start
endDate	ISO-8601	optional range end for recurring
billingCycleCodes	string[]	required, non-empty — the cycles each run will bill
processType	enum	AUTOMATIC / MANUAL / FULL_AUTOMATIC
lastTransactionDate / invoiceDate	ISO-8601	optional; else resolved from each cycle's EL
rejectAutoAction / suspectAutoAction	enum	MOVE / CANCEL / CANCEL_RT / AUTOMATIC_VALIDATION / MANUAL_ACTION
generateAO	boolean	create accounting entries for each invoice
computeDatesAtValidation	boolean	defer date computation to the validation step
active	boolean	default true; false = create paused

Aggregation rules come from the billing cycle

A scheduled BillingRunJob inherits its aggregation rules (ignoreOrders, dateAggregation, etc.) from each billing cycle it processes — not from the schedule. To change aggregation behaviour for a scheduled run, edit the billing cycle. (One-off runs via POST /api/v1/billingRuns carry their own aggregation rules — see Bill Runs.)

Lifecycle

created (ACTIVE) ──▶ fires on timer ──▶ creates a BillingRun (NEW) ──▶ job chain advances it
       │
       ├─ pause ──▶ PAUSED ──▶ resume ──▶ ACTIVE
       └─ one-time: after firing ──▶ COMPLETED

BRs produced by a schedule show Created by: Schedule: {code} on the Bill Runs list, linking back to the schedule.

Managing schedules in the UI

/billRuns/schedules lists every schedule with its human-readable cadence, cycles, status, last run, and next fire time. Row actions: Run now, Pause/Resume, Edit, Delete. The create/edit forms use the visual CronBuilder for the cadence.

Errors

Code	Cause
400 MISSING_NAME	name is blank.
400 MISSING_BILLING_CYCLES	billingCycleCodes empty.
400 INVALID_REPEATS	unknown repeats value.
400 INVALID_PROCESS_TYPE / INVALID_AUTO_ACTION	unknown enum value.
409 SCHEDULE_EXISTS	a schedule with that name already exists.
404 SCHEDULE_NOT_FOUND	unknown code on get / update / delete / action.