Consumptions

Base URL: $BUSINESS_API

List accepted consumptions

Logs

GET /consumptions

List immutable consumption records selected from accepted readings

Returns the tenant's stored consumption records, one cursor page at a time. Each record covers one meter and billing cycle, references the accepted readings it was computed from, and states whether it is actual or estimated. Requires business:consumptions:read; an unknown method value or an invalid cursor returns 400.

Parameters

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

meter_idstring · query · optional

Return only consumptions computed for this meter ID.

account_idstring · query · optional

Return only consumptions belonging to this account ID (the account the meter was assigned to when the consumption was recorded).

cycle_idstring · query · optional

Return only consumptions recorded for this billing cycle identifier.

methodstring · query · optional

Return only consumptions of this kind: actual when both readings were actual, estimated when either reading was estimated; empty returns both.

one of actual, estimated

Returns

200 Consumption records with selected reading IDs preserved

Permissions business:consumptions:read · Roles: admin, analyst, billing_clerk, customer_service, field_supervisor, finance, operations, owner, viewer

curl -X GET "$BUSINESS_API/consumptions" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Consumption records with selected reading IDs preserved

Create accepted consumption

Logs

POST /consumptions

Select accepted readings and persist immutable meter consumption

Computes consumption for one meter between period_start and period_end and stores it as an immutable record for the given cycle_id. The baseline is the latest accepted reading at or before the period start (or the meter's installation time if it was installed inside the period) and the end is the latest accepted reading at or before period_end; meter resets and rollovers in between are accounted for. The result is marked estimated when either reading was estimated. Requires business:consumptions:create; missing fields or period_end not after period_start return 400, an unknown meter returns 404, and 409 is returned when no usable pair of accepted readings exists or a consumption already exists for that meter and cycle.

Body application/json

meter_idstring · required
cycle_idstring · required
period_startstring (date-time) · required
period_endstring (date-time) · required

Returns

201 Consumption selected and recorded for billing

Show attributes
idstring · required
tenant_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 · required
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.

cycle_idstring · required
period_startstring (date-time) · required
period_endstring (date-time) · required
from_reading_idstring · required
to_reading_idstring · required
valuestring · required
unitstring · required
methodstring · required

one of actual, estimated

created_atstring (date-time) · required

Permissions business:consumptions:create · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/consumptions" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "meter_id": "mtr_21F02THKOD7uMpvUalZKsBv64nN",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z"
}'
Response 201
{
  "id": "con_2nR0I9tA6XXk4bxUyjPqmvxi8nN",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "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",
  "cycle_id": "cyc_2o6Z32az1oKF1ykfNkmdxACDLcy",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "from_reading_id": "fro_2zXkivBGsXvOyvPqMFry433gEp5",
  "to_reading_id": "tor_2YMhF6MrDmIFLAyjLcYXv4YbHMe",
  "value": "value",
  "unit": "unit",
  "method": "actual",
  "created_at": "2026-11-19T09:30:00Z"
}