Billing schedules

Base URL: $BUSINESS_API

The object

namestring · required
service_area_idstring · optional
day_of_monthinteger · required
due_daysinteger · required
estimate_missingboolean · optional
auto_consumptionboolean · optional · default true
idstring · optional
tenant_idstring · optional
statusstring · optional

one of active, paused

next_run_atstring (date-time) · optional
last_run_atstring (date-time) · optional
last_run_idstring · optional
last_errorstring · optional
The object
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

List billing schedules

Logs

GET /billing-schedules

Returns the tenant's billing schedules with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status (active or paused). Each schedule shows its day of month, due days, service area, next run time and next period start. 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 Schedules

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

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

Schedules

Create billing schedule

Logs

POST /billing-schedules

Create a monthly billing schedule for the tenant or one service area

Creates an active schedule that starts a billing run each month on day_of_month (1 to 28), covering the month before that day; holidays in the tenant calendar are skipped when computing next_run_at. due_days must be 0 to 180 and auto_consumption defaults to true. Only one schedule may cover the whole tenant or a given service area, and a tenant-wide schedule excludes area schedules, so an overlap answers 409. Requires billing_runs:write and returns 201.

Body application/json

namestring · required
service_area_idstring · optional
day_of_monthinteger · required
due_daysinteger · required
estimate_missingboolean · optional
auto_consumptionboolean · optional · default true

Returns

201 Schedule

Show attributes
namestring · required
service_area_idstring · optional
day_of_monthinteger · required
due_daysinteger · required
estimate_missingboolean · optional
auto_consumptionboolean · optional · default true
idstring · optional
tenant_idstring · optional
statusstring · optional

one of active, paused

next_run_atstring (date-time) · optional
last_run_atstring (date-time) · optional
last_run_idstring · optional
last_errorstring · optional

Errors 409

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

curl -X POST "$BUSINESS_API/billing-schedules" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true
}'
Response 201
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

Read a billing schedule

Logs

GET /billing-schedules/{id}

Returns one billing schedule with its name, service area, day of month, due days, estimate and auto-consumption flags, status, next run time and next period start. Answers 404 when the schedule is not in the caller's tenant.

Parameters

idstring · path · required

Identifier of the billing schedule (prefix bsc_).

Returns

200 Schedule

Show attributes
namestring · required
service_area_idstring · optional
day_of_monthinteger · required
due_daysinteger · required
estimate_missingboolean · optional
auto_consumptionboolean · optional · default true
idstring · optional
tenant_idstring · optional
statusstring · optional

one of active, paused

next_run_atstring (date-time) · optional
last_run_atstring (date-time) · optional
last_run_idstring · optional
last_errorstring · optional

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

curl -X GET "$BUSINESS_API/billing-schedules/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}

Update or pause a billing schedule

Logs

PATCH /billing-schedules/{id}

Applies only the fields present in the body; status accepts active or paused, and the same limits as on create apply (day_of_month 1 to 28, due_days 0 to 180). Resuming a paused schedule or changing day_of_month recomputes next_run_at from now, so missed months are not billed retroactively; other edits keep the period already scheduled. Requires billing_runs:write.

Parameters

idstring · path · required

Identifier of the billing schedule to update (prefix bsc_).

Body application/json

namestring · optional
day_of_monthinteger · optional
due_daysinteger · optional
estimate_missingboolean · optional
auto_consumptionboolean · optional
statusstring · optional

one of active, paused

Returns

200 Schedule

Show attributes
namestring · required
service_area_idstring · optional
day_of_monthinteger · required
due_daysinteger · required
estimate_missingboolean · optional
auto_consumptionboolean · optional · default true
idstring · optional
tenant_idstring · optional
statusstring · optional

one of active, paused

next_run_atstring (date-time) · optional
last_run_atstring (date-time) · optional
last_run_idstring · optional
last_errorstring · optional

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

curl -X PATCH "$BUSINESS_API/billing-schedules/{id}" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Ana Matsinhe",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "status": "active"
}'
Response 200
{
  "name": "Ana Matsinhe",
  "service_area_id": "ser_23fmkpfkC17kSVJ2spjyiBbOED9",
  "day_of_month": 1,
  "due_days": 125000,
  "estimate_missing": true,
  "auto_consumption": true,
  "id": "bsc_2VbGk5JU4zBiCn962nHw0nZW0X9",
  "tenant_id": "ten_2ugFXIC316WXzGu1HGal90AxTA6",
  "status": "active",
  "next_run_at": "2026-11-19T09:30:00Z",
  "last_run_at": "2026-11-19T09:30:00Z",
  "last_run_id": "las_288dXcAFBUYTZK8DFgClTcAHRou",
  "last_error": "last error"
}