Billing policy

Base URL: $BUSINESS_API

The object

tenant_idstring · optional
default_due_daysinteger · optional
grace_period_daysinteger · optional
default_missing_reading_m3number · optional · nullable

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · optional
late_penalty_kindstring · optional
late_penalty_amount_minorinteger (int64) · optional
late_penalty_rate_basis_pointsinteger (int64) · optional
late_penalty_frequencystring · optional
late_penalty_interval_daysinteger · optional
late_penalty_cap_minorinteger (int64) · optional
late_penalty_taxableboolean · optional
late_penalty_compoundboolean · optional
exclude_disputed_from_penaltyboolean · optional
exclude_payment_plan_from_penaltyboolean · optional
versioninteger · optional
updated_atstring (date-time) · optional
The object
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Read the utility billing policy

Logs

GET /billing-policy

Returns the tenant's billing policy: default due days, grace period, the default volume used for missing readings, and the late penalty settings (kind, amount or rate, frequency, interval, cap, tax and compounding, and exclusions for disputed invoices and payment plans). A tenant that never saved a policy gets the default policy. Requires tariffs:read.

Returns

200 Billing policy

Show attributes
tenant_idstring · optional
default_due_daysinteger · optional
grace_period_daysinteger · optional
default_missing_reading_m3number · optional · nullable

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · optional
late_penalty_kindstring · optional
late_penalty_amount_minorinteger (int64) · optional
late_penalty_rate_basis_pointsinteger (int64) · optional
late_penalty_frequencystring · optional
late_penalty_interval_daysinteger · optional
late_penalty_cap_minorinteger (int64) · optional
late_penalty_taxableboolean · optional
late_penalty_compoundboolean · optional
exclude_disputed_from_penaltyboolean · optional
exclude_payment_plan_from_penaltyboolean · optional
versioninteger · optional
updated_atstring (date-time) · optional

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

curl -X GET "$BUSINESS_API/billing-policy" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Update the utility billing policy

Logs

PUT /billing-policy

Applies only the fields present in the body to the current policy, then validates the result: due days, grace period and penalty cap must not be negative, the default missing-reading volume must be a non-negative finite number, and late_penalty_frequency must be one_time or recurring (the default). When late penalties are enabled the chosen kind needs its amount or rate, for example a positive late_penalty_amount_minor for a fixed penalty. Send clear_default_missing_reading true to remove the default volume. Requires tariffs:write; returns the saved policy or 400.

Body application/json

default_due_daysinteger · optional
grace_period_daysinteger · optional
default_missing_reading_m3number · optional · nullable
clear_default_missing_readingboolean · optional
late_penalty_enabledboolean · optional
late_penalty_kindstring · optional
late_penalty_amount_minorinteger (int64) · optional
late_penalty_rate_basis_pointsinteger (int64) · optional
late_penalty_frequencystring · optional
late_penalty_interval_daysinteger · optional
late_penalty_cap_minorinteger (int64) · optional
late_penalty_taxableboolean · optional
late_penalty_compoundboolean · optional
exclude_disputed_from_penaltyboolean · optional
exclude_payment_plan_from_penaltyboolean · optional

Returns

200 Updated billing policy

Show attributes
tenant_idstring · optional
default_due_daysinteger · optional
grace_period_daysinteger · optional
default_missing_reading_m3number · optional · nullable

Default consumption in m3 used when a reading is missing and no history exists.

late_penalty_enabledboolean · optional
late_penalty_kindstring · optional
late_penalty_amount_minorinteger (int64) · optional
late_penalty_rate_basis_pointsinteger (int64) · optional
late_penalty_frequencystring · optional
late_penalty_interval_daysinteger · optional
late_penalty_cap_minorinteger (int64) · optional
late_penalty_taxableboolean · optional
late_penalty_compoundboolean · optional
exclude_disputed_from_penaltyboolean · optional
exclude_payment_plan_from_penaltyboolean · optional
versioninteger · optional
updated_atstring (date-time) · optional

Errors 422

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

curl -X PUT "$BUSINESS_API/billing-policy" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "default_due_days": 125000,
  "grace_period_days": 0,
  "default_missing_reading_m3": 13.42,
  "clear_default_missing_reading": true,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true
}'
Response 200
{
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "default_due_days": 125000,
  "grace_period_days": 1,
  "default_missing_reading_m3": 13.42,
  "late_penalty_enabled": true,
  "late_penalty_kind": "late penalty kind",
  "late_penalty_amount_minor": 125000,
  "late_penalty_rate_basis_points": 1,
  "late_penalty_frequency": "late penalty frequency",
  "late_penalty_interval_days": 1,
  "late_penalty_cap_minor": 1,
  "late_penalty_taxable": true,
  "late_penalty_compound": true,
  "exclude_disputed_from_penalty": true,
  "exclude_payment_plan_from_penalty": true,
  "version": 1,
  "updated_at": "2026-11-19T09:30:00Z"
}

Apply late payment penalties to overdue invoices now

Logs

POST /billing-policy/assess-late-penalties

Runs the tenant's late penalty policy immediately instead of waiting for the scheduled run. Each open invoice with a balance whose due date plus the grace period has passed gets a late fee debit note, fixed or a percentage of the overdue balance and limited by the cap, unless the policy excludes disputed invoices or accounts on an active payment plan. Penalties are idempotent per invoice, policy version and recurrence cycle, so calling again does not charge twice. When late penalties are disabled in the billing policy nothing is applied and applied is 0. No request body is read. Requires invoices:write.

Returns

200 Number of penalties applied by this run

Show attributes
appliedinteger · required

Late fee debit notes created by this call.

Errors 400 · 401 · 403

Permissions invoices:write · Roles: admin, billing_clerk, finance, owner

curl -X POST "$BUSINESS_API/billing-policy/assess-late-penalties" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "applied": 3
}