Reading cycles

Base URL: $BUSINESS_API

List reading cycles

Logs

GET /reading-cycles

Returns a cursor-paginated page of the tenant's reading cycles, each with its code, billing frequency and the day of the month readings are scheduled. You can also pass q for a text search, limit (default 20, maximum 100) and after. Requires the business:reading-cycles:read permission.

Parameters

activeboolean · query · optional

Boolean filter (true/false, also 1/0): true returns only active cycles, false only inactive ones; omit it to return both, and a value that is not a boolean returns 400.

qstring · query · optional

Resource-specific text search.

limitinteger · query · optional

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

afterstring · query · optional

Opaque cursor returned by the previous page.

Returns

200 Reading cycles

Permissions business:reading-cycles:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

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

Reading cycles

Create a reading cycle

Logs

POST /reading-cycles

Creates a reading cycle that groups routes and readings into a billing period and returns it as active. code is required (at most 60 characters), name is optional (at most 255), billing_frequency must be monthly, bimonthly, quarterly, semiannual or annual, and schedule_day_of_month must be between 1 and 28; other values return 400. A code already used in the tenant returns 409. Requires business:reading-cycles:manage.

Body application/json

idstring · optional
codestring · required
namestring · optional
billing_frequencystring · required

one of monthly, bimonthly, quarterly, semiannual, annual

schedule_day_of_monthinteger · required
activeboolean · optional

Returns

201 Cycle created

Permissions business:reading-cycles:manage · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/reading-cycles" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "id": "rea_21jyIxPwENBKepLmS7BEoTx82lx",
  "code": "COD-2026-000142",
  "name": "Ana Matsinhe",
  "billing_frequency": "monthly",
  "schedule_day_of_month": 1,
  "active": true
}'
Response 201

Cycle created

Get a reading cycle

Logs

GET /reading-cycles/{id}

Returns one reading cycle with its code, name, billing frequency, schedule day and whether it is active. A cycle that does not exist in the tenant returns 404. Requires the business:reading-cycles:read permission.

Parameters

idstring · path · required

ID of the reading cycle to return.

Returns

200 Cycle

Permissions business:reading-cycles:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner

curl -X GET "$BUSINESS_API/reading-cycles/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

Cycle

Update a reading cycle

Logs

PATCH /reading-cycles/{id}

Changes only the fields present in the body (name, billing_frequency, schedule_day_of_month, active) and returns the updated cycle; the code cannot be changed. billing_frequency must be monthly, bimonthly, quarterly, semiannual or annual and schedule_day_of_month between 1 and 28, otherwise the call returns 400. Setting active to false deactivates the cycle without deleting it. Requires business:reading-cycles:manage.

Parameters

idstring · path · required

ID of the reading cycle to update.

Body application/json

namestring · optional
billing_frequencystring · optional

one of monthly, bimonthly, quarterly, semiannual, annual

schedule_day_of_monthinteger · optional
activeboolean · optional

Returns

200 Updated cycle

Permissions business:reading-cycles:manage · Roles: admin, operations, owner

curl -X PATCH "$BUSINESS_API/reading-cycles/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "billing_frequency": "monthly",
  "schedule_day_of_month": 1,
  "active": true
}'
Response 200

Updated cycle