Reconciliation contracts

Base URL: $BUSINESS_API

List operator and agent commission agreements

Logs

GET /reconciliation-contracts

Returns a cursor-paginated page of operator commission contracts, each binding a meter (and optionally an account or connection) to an operator or agent for a term with a commission rate. Filter with status, meter_id or account_id and page with limit and after. An active contract whose end date has passed is shown as expired. Requires business:reconciliations: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 OK

Permissions business:reconciliations:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

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

OK

Create an operator or agent commission agreement on a meter

Logs

POST /reconciliation-contracts

Creates an operator or agent commission contract for a meter and returns it in draft status. meter_id and operator_name are required, end_date must be after start_date, and commission_bp must be between 0 and 10000 basis points; the meter must exist in the tenant. The contract does not take effect until its status is set to active. Requires business:reconciliations:write.

Returns

200 OK

Permissions business:reconciliations:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/reconciliation-contracts" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200

OK

Get a commission agreement

Logs

GET /reconciliation-contracts/{id}

Returns one operator commission contract with its meter, operator details, term, commission rate and status. An active contract whose end date has passed is reported as expired. A contract that does not exist in the tenant returns 404. Requires business:reconciliations:read.

Returns

200 OK

Permissions business:reconciliations:read · Roles: admin, analyst, customer_service, finance, operations, owner, viewer

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

OK

Activate, suspend or terminate a commission agreement

Logs

POST /reconciliation-contracts/{id}/status

Moves a contract to a new status and returns the updated contract. Allowed moves are draft to active or terminated, active to suspended, terminated or expired, and suspended to active or terminated; any other move returns 409. Activating also returns 409 when the meter already has another active contract. Requires business:reconciliations:write.

Returns

200 OK

Permissions business:reconciliations:write · Roles: admin, operations, owner

curl -X POST "$BUSINESS_API/reconciliation-contracts/{id}/status" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200

OK