Billing runs

Base URL: $BUSINESS_API

The object

idstring · required
tenant_idstring · required
service_area_idstring · optional
schedule_idstring · optional
period_startstring (date-time) · required
period_endstring (date-time) · required
total_invoicesinteger · required
total_amount_centsinteger · required
statusstring · required

one of pending, running, completed, failed

issued_invoicesinteger · required

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · required

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · required
estimated_invoicesinteger · required
exception_countinteger · required
error_messagestring · optional
created_atstring (date-time) · required
completed_atstring (date-time) · optional
The object
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

List billing execution runs

Logs

GET /billing-runs

Returns the tenant's billing runs with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status. Each run shows its period, service area, status, issued, skipped and estimated invoice counts, total amount and exception count. Requires billing_runs:read.

Parameters

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Billing runs

Show attributes
dataarray of BillingRun · required
Show child attributes
idstring · required
tenant_idstring · required
service_area_idstring · optional
schedule_idstring · optional
period_startstring (date-time) · required
period_endstring (date-time) · required
total_invoicesinteger · required
total_amount_centsinteger · required
statusstring · required

one of pending, running, completed, failed

issued_invoicesinteger · required

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · required

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · required
estimated_invoicesinteger · required
exception_countinteger · required
error_messagestring · optional
created_atstring (date-time) · required
completed_atstring (date-time) · optional
has_moreboolean · required
next_cursorstring · optional
total_countinteger · optional

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
      "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
      "period_start": "2026-11-19T09:30:00Z",
      "period_end": "2026-11-19T09:30:00Z",
      "total_invoices": 125000,
      "total_amount_cents": 125000,
      "status": "pending",
      "issued_invoices": 1,
      "issued_amount_cents": 125000,
      "skipped_accounts": 1,
      "estimated_invoices": 1,
      "exception_count": 1,
      "error_message": "error message",
      "created_at": "2026-11-19T09:30:00Z",
      "completed_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Trigger a periodic billing run

Logs

POST /billing-runs

Issues one invoice per account for the period from accepted consumptions; period_start must be before period_end and due_date, when given, must not fall before period_end. A period is billed by one run: calling again for the same period and service area reuses that run and skips accounts already invoiced, so retrying after a partial failure is safe. When the job queue is enabled and the period is large, the run is queued and returned in running status for you to poll. Records billing_run.started and then billing_run.posted or billing_run.failed events, plus exception events for skipped accounts; requires billing_runs:write and the billing capability, and returns 201.

Body application/json

period_startstring (date-time) · required
period_endstring (date-time) · required
due_datestring (date-time) · optional
service_area_idstring · optional
auto_consumptionboolean · optional
estimate_missingboolean · optional

Returns

201 Billing run started

Show attributes
idstring · required
tenant_idstring · required
service_area_idstring · optional
schedule_idstring · optional
period_startstring (date-time) · required
period_endstring (date-time) · required
total_invoicesinteger · required
total_amount_centsinteger · required
statusstring · required

one of pending, running, completed, failed

issued_invoicesinteger · required

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · required

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · required
estimated_invoicesinteger · required
exception_countinteger · required
error_messagestring · optional
created_atstring (date-time) · required
completed_atstring (date-time) · optional

Errors 403

Permissions billing_runs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "due_date": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "auto_consumption": true,
  "estimate_missing": true
}'
Response 201
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

Get a billing execution run

Logs

GET /billing-runs/{id}

Returns one billing run with its period, service area, schedule, status, invoice counts, total amount, exception count, error message and completion time. Poll it after a queued run to see when it completes. Answers 404 when the run is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the billing run (prefix brn_).

Returns

200 Billing run

Show attributes
idstring · required
tenant_idstring · required
service_area_idstring · optional
schedule_idstring · optional
period_startstring (date-time) · required
period_endstring (date-time) · required
total_invoicesinteger · required
total_amount_centsinteger · required
statusstring · required

one of pending, running, completed, failed

issued_invoicesinteger · required

Invoices issued by the most recent execution of this run.

issued_amount_centsinteger (int64) · required

Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.

skipped_accountsinteger · required
estimated_invoicesinteger · required
exception_countinteger · required
error_messagestring · optional
created_atstring (date-time) · required
completed_atstring (date-time) · optional

Errors 404

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "id": "brn_2fnCKRfkezDig1bGCBlcUfDW45V",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "schedule_id": "sch_277GSDJgyxdmMHr4kPVUg5dswJl",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "total_invoices": 125000,
  "total_amount_cents": 125000,
  "status": "pending",
  "issued_invoices": 1,
  "issued_amount_cents": 125000,
  "skipped_accounts": 1,
  "estimated_invoices": 1,
  "exception_count": 1,
  "error_message": "error message",
  "created_at": "2026-11-19T09:30:00Z",
  "completed_at": "2026-11-19T09:30:00Z"
}

Report what a billing run would issue

Logs

POST /billing-runs/preview

Report what a billing run would issue, with no side effects

Takes the same body as executeBillingRun and returns, per account, the invoice that would be issued (consumption, line items, charges, tax, reconciliation, arrears, due date and payment instructions) plus the exceptions that would be raised and the totals. Nothing is stored or issued and no event is recorded. capability_active reports whether the billing capability is on, so a run would actually be allowed. Requires billing_runs:read.

Body application/json

period_startstring (date-time) · required
period_endstring (date-time) · required
due_datestring (date-time) · optional
service_area_idstring · optional
auto_consumptionboolean · optional
estimate_missingboolean · optional

Returns

200 Invoices that would be issued and accounts that would be skipped, with capability_active

Show attributes
period_startstring (date-time) · optional
period_endstring (date-time) · optional
service_area_idstring · optional
capability_activeboolean · optional
invoice_countinteger · optional
estimated_countinteger · optional
total_amount_centsinteger · optional
exception_countinteger · optional
invoicesarray of object · optional
exceptionsarray of object · optional

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X POST "$BUSINESS_API/billing-runs/preview" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "due_date": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "auto_consumption": true,
  "estimate_missing": true
}'
Response 200
{
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "capability_active": true,
  "invoice_count": 1,
  "estimated_count": 1,
  "total_amount_cents": 125000,
  "exception_count": 1,
  "invoices": [
    {}
  ],
  "exceptions": [
    {}
  ]
}

Re-run unresolved accounts for an existing billing run

Logs

POST /billing-runs/{id}/retry

Executes the run's period again: accounts already invoiced are skipped, accounts that failed or were not billable before are attempted again, and the run's counts and exceptions are replaced with the new outcome. Exceptions that were dismissed before are dismissed again with the same note when they recur. Estimates are used again only if the original run issued estimated invoices. Requires billing_runs:write and returns the updated run.

Parameters

idstring · path · required

Identifier of the billing run to retry (prefix brn_).

Returns

200 Updated billing run

Permissions billing_runs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs/{id}/retry" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Updated billing run

Resolve or dismiss a billing run exception

Logs

POST /billing-runs/{id}/exceptions/{exceptionId}/resolve

Sets the exception's review status to resolved (the default) or dismissed, and records who did it, when, and an optional resolution note. Any other status answers 400, and an exception that does not belong to the run in the path answers 404. Dismissals are carried over when the run is retried. Requires billing_runs:write.

Parameters

idstring · path · required

Identifier of the billing run the exception belongs to (prefix brn_).

exceptionIdstring · path · required

Identifier of the exception to resolve or dismiss (prefix rex_).

Body application/json

statusstring · optional

one of resolved, dismissed

resolution_notestring · optional

Returns

200 Updated exception

Permissions billing_runs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs/{id}/exceptions/{exceptionId}/resolve" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "status": "resolved",
  "resolution_note": "resolution note"
}'
Response 200

Updated exception

Accounts a run skipped and why

Logs

GET /billing-runs/{id}/exceptions

Returns the accounts the run skipped or failed to bill, each with the reason, detail and review status, with cursor pagination (limit defaults to 20, at most 100). Filter by reason or by status (open, resolved or dismissed). Answers 404 when the run is not in the tenant.

Parameters

idstring · path · required

Identifier of the billing run whose exceptions to list (prefix brn_).

limitinteger · query · optional

Maximum resources to return (default 20, maximum 100).

afterstring · query · optional

Opaque cursor returned by the previous page.

reasonstring · query · optional

Return only exceptions with this reason: already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed or reconciliation_credit_exceeds_bill.

one of already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed, reconciliation_credit_exceeds_bill

Returns

200 Exceptions

Show attributes
dataarray of RunException · required
Show child attributes
idstring · required
tenant_idstring · required
run_idstring · required
account_idstring · required
account_numberstring · optional

Number of the referenced account, e.g. CTA-000044. Omitted when unknown.

account_holder_namestring · optional

Display name of the customer who holds the referenced account. Omitted when unknown.

meter_idstring · optional
meter_serialstring · optional

Serial number of the referenced meter. Omitted when unknown.

meter_holder_namestring · optional

Display name of the customer who holds the account the meter is installed on. Omitted when unknown.

reasonstring · required

one of already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed, reconciliation_credit_exceeds_bill

detailstring · optional
created_atstring (date-time) · required
has_moreboolean · required
next_cursorstring · optional
total_countinteger · optional

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}/exceptions" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "data": [
    {
      "id": "run_21N6eP9iEDLkipnkOBnWWxpc4XP",
      "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
      "run_id": "run_2VvMAN1CyVnimXb8yn1Qon7gqrJ",
      "account_id": "act_2JFioNDgIfvkgflk8RtcqhBaARP",
      "account_number": "ACC-2026-000142",
      "account_holder_name": "Ana Matsinhe",
      "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
      "meter_serial": "meter serial",
      "meter_holder_name": "Ana Matsinhe",
      "reason": "already_billed",
      "detail": "detail",
      "created_at": "2026-11-19T09:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "next cursor",
  "total_count": 125000
}

Download the finished invoice PDF archive

Logs

GET /billing-runs/{id}/invoice-pdfs

Streams the ZIP archive prepared by enqueueInvoicePdfBatch, as an attachment whose file name depends on the negotiated document language. Answers 404 while no archive exists for the run, so check the status endpoint first.

Parameters

idstring · path · required

Identifier of the billing run whose archive to download (prefix brn_).

Returns

200 ZIP archive

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}/invoice-pdfs" \
  -H "Authorization: Bearer sk_test_..."
Response 200

ZIP archive

Queue a PDF archive of every invoice of a billing run

Logs

POST /billing-runs/{id}/invoice-pdfs

Queue a PDF archive of every invoice of a billing run (job queue enabled)

Queues a background job that renders the PDF of every invoice issued by the run into one ZIP archive, and answers 202 with job_id and status. Repeating the call for the same run reuses the queued job. Requires billing_runs:write; answers 404 for an unknown run and 409 when background jobs are not enabled on the installation.

Parameters

idstring · path · required

Identifier of the billing run whose invoices to archive (prefix brn_).

Returns

202 The queued job id

Errors 409

Permissions billing_runs:write · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/billing-runs/{id}/invoice-pdfs" \
  -H "Authorization: Bearer sk_test_..."
Response 202

The queued job id

Get invoice pdf batch status

Logs

GET /billing-runs/{id}/invoice-pdfs/status

Whether the invoice PDF archive can be prepared and is ready, without a 404 while it is absent

Returns enabled, which says whether background jobs can prepare an archive on this installation, and available, which says whether a finished archive for the run can be downloaded now. It answers 200 in both cases so a client can poll after queuing; 404 only when the run itself is unknown.

Parameters

idstring · path · required

Identifier of the billing run whose archive status to read (prefix brn_).

Returns

200 The archive state

Show attributes
enabledboolean · required

False when this installation runs without the job queue

availableboolean · required

True when a finished archive can be downloaded

Permissions billing_runs:read · Roles: admin, analyst, billing_clerk, customer_service, finance, owner, viewer

curl -X GET "$BUSINESS_API/billing-runs/{id}/invoice-pdfs/status" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "enabled": true,
  "available": true
}