Bill Runs

A bill run turns rated transactions into invoices. Billerang exposes a single universal API for creating and running bill runs — there is no distinction between "cycle" and "ad-hoc" bill runs in the public contract.

The universal model

The universal bill run carries its own scope and aggregation rules. There is no inheritance from a billing cycle by default — when you attach a cycle, its fields become defaults for the BR, not constraints.

POST /api/v1/billingRuns (sync) and POST /api/v1/billingRuns/async (async + jobRunId).

Run types are auto-derived

Condition	runType
billingCycleCode is set	CYCLE
billingCycleCode is null	EXCEPTIONAL

You do not pick the run type — it follows from the scope you provide.

Scope sources

A bill run picks RatedTransactions through the intersection of four optional sources:

Source	Effect
billingCycleCode	Bill all BAs assigned to the cycle. Inherits the BC's invoiceTypeEl, splitPerPaymentMethod, aggregation defaults, and validation script.
billingAccountCodes[]	Explicit BA list. Combinable with the cycle (intersection).
filters (generic-API map)	JPA-path filters on RatedTransaction. Operator prefixes supported: inList, fromRange, toRange, like, ne, gt, lt.
applicationEl (run gate, not a BA filter)	Jakarta EL evaluated at job execution time. When false → the entire BR is skipped by the job.

To filter BAs or charges, use filters — not applicationEl.

Date semantics

The bill run consumes RatedTransactions that already exist. Charge-level nextChargeDate / nextInvoiceDate (on ChargeInstance) drive WO → RT generation by the rating engine — they are not bill-run inputs.

Date	Role
invoiceDate	Date stamped on invoices the run produces.
lastTransactionDate	RT cutoff. Only RTs with usageDate < lastTransactionDate enter the run.
startDate / endDate (advanced)	Filter billingAccount.nextInvoiceDate ∈ [startDate, endDate].

Process modes

processType controls the engine behaviour — how far the engine advances the BR's status.

UI label	Backend value	Result
Automated, ready for validation	AUTOMATIC	Stops at DRAFT_INVOICES; operator validates.
Manual progress	MANUAL	Stays at NEW; operator advances each step.
Automated validation	FULL_AUTOMATIC	Runs end-to-end including validation, reaches VALIDATED.

runOptions.autoValidate is a separate HTTP-level flag for sync POSTs: block the response until VALIDATED. Only valid with processType=FULL_AUTOMATIC (other combos return 400).

Minimal example — bill one BA right now

TOKEN=$(./get-token.sh)
curl -X POST "https://api.billerang.com/api/v1/billingRuns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "billingAccountCodes": ["BA_001"],
    "invoiceDate": "2026-05-13T00:00:00Z",
    "lastTransactionDate": "2026-05-13T23:59:59Z",
    "processType": "FULL_AUTOMATIC",
    "runOptions": { "autoValidate": true }
  }'

Returns the full BR with status: "VALIDATED".

Cycle-based example — monthly run for all B2C accounts

curl -X POST "https://api.billerang.com/api/v1/billingRuns" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "code": "BR_MONTHLY_B2C_2026_05",
    "description": "Monthly B2C billing",
    "billingCycleCode": "Monthly_B2C",
    "invoiceDate": "2026-05-01T00:00:00Z",
    "lastTransactionDate": "2026-04-30T23:59:59Z",
    "processType": "AUTOMATIC"
  }'

code is the idempotency key — submitting the same code twice returns 409.

Filtered example — only USAGE charges for B2M customers

curl -X POST "https://api.billerang.com/api/v1/billingRuns" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "invoiceDate": "2026-05-13T00:00:00Z",
    "lastTransactionDate": "2026-05-13T23:59:59Z",
    "filters": {
      "chargeInstance.chargeTemplate.chargeMainType": "USAGE",
      "billingAccount.customer.customerCategory.code": "B2M"
    },
    "processType": "FULL_AUTOMATIC",
    "runOptions": { "autoValidate": true }
  }'

Full payload reference

See Aggregation Rules for the full set of aggregation knobs and Split Billing for the five native split mechanisms.

Field	Type	Required	Default
code	string	no	auto-generated
description	string	no	—
billingCycleCode	string	no	—
billingAccountCodes	string[]	no	—
filters	object	no	—
applicationEl	string	no	—
defaultInvoiceTypeCode	string	no	— (resolved per article)
invoiceDate	ISO-8601	yes	—
lastTransactionDate	ISO-8601	yes	—
processType	enum	no	FULL_AUTOMATIC
validationScriptCode	string	no	— (cycle's script)
disableAggregation	boolean	no	entity default
dateAggregation	enum	no	MONTH_OF_USAGE_DATE
discountAggregation	enum	no	FULL_AGGREGATION
useAccountingArticleLabel	boolean	no	false (UI shows TRUE)
aggregateUnitAmounts	boolean	no	false
ignoreSubscriptions	boolean	no	true
ignoreOrders	boolean	no	true (UI shows OFF)
ignoreUserAccounts	boolean	no	true
ignoreServiceInstances	boolean	no	true
incrementalInvoiceLines	boolean	no	false
additionalAggregationFields	string[]	no	[]
runOptions.autoValidate	boolean	no	false
runOptions.applyMinimum	boolean	no	false
runOptions.applyThreshold	boolean	no	false
runOptions.applyDiscount	boolean	no	false
runOptions.rejectAutoAction	enum	no	MOVE
runOptions.suspectAutoAction	enum	no	MOVE
runOptions.computeDatesAtValidation	boolean	no	false
runOptions.skipValidationScript	boolean	no	false

What happens after submit

The bill run progresses through a status pipeline driven by three independent jobs:

   ┌──────────────┐   ┌──────────────────┐   ┌─────────────────┐   ┌──────────────┐
   │ BillingRun   │──▶│ InvoiceLinesJob  │──▶│ InvoicingJob    │──▶│ PDF / XML    │
   │ created NEW  │   │ _V2              │   │ _V2 / _V3       │   │ jobs         │
   └──────────────┘   └──────────────────┘   └─────────────────┘   └──────────────┘

For one-off API-driven runs, POST /api/v1/billingRuns fires the chain immediately. For recurring runs, configure a BillingRunJob JobInstance with a cron schedule + cycle list. See the section on scheduling below.

Recurring & one-time scheduled runs

The bill run entity itself has no schedule field. Scheduling is a first-class API: /api/v1/billingRunSchedules — see Scheduled Runs for the full reference.

In short, a schedule is a thin wrapper over a BillingRunJob JobInstance + its TimerEntity:

• One-time (repeats: "NONE") — "schedule it before running it": fires once at a chosen date/time.
• Recurring (repeats: "DAILY" | "WEEKLY" | "MONTHLY") — fires on a cron cadence.

The New Bill Run form's cadence selector (Run now / Run once at… / Recurring) routes the non-"now" choices to the schedule form. Manage schedules from /billRuns/schedules.

Errors

Code	Cause
400 MISSING_INVOICE_DATE	invoiceDate missing.
400 INVALID_AUTO_VALIDATE_COMBO	processType=AUTOMATIC or MANUAL with runOptions.autoValidate=true (deadlock).
400 INVALID_DATE_AGGREGATION	Unknown dateAggregation value.
400 INVALID_DISCOUNT_AGGREGATION	Unknown discountAggregation value.
400 UNKNOWN_BILLING_ACCOUNT	A code in billingAccountCodes does not exist.
400 UNKNOWN_BILLING_CYCLE	billingCycleCode does not exist.
400 UNKNOWN_INVOICE_TYPE	defaultInvoiceTypeCode does not exist.
400 UNKNOWN_VALIDATION_SCRIPT	validationScriptCode does not exist.
409	Duplicate code.
422 NO_BILLABLE_TRANSACTIONS	Filters + dates match no RTs/WOs.

See also

• Aggregation Rules — what every aggregation knob does, with worked examples.
• Split Billing — the five native mechanisms that produce multiple invoices per BA.
• Quarantine Review — handling rejected and suspect invoices.
• Scheduled Runs — recurring and one-time scheduled bill runs.