Metered reconciliations

Base URL: $BUSINESS_API

List metered volume and remittance reconciliations

Logs

GET /metered-reconciliations

Returns the tenant's metered reconciliations with their computed expected amount, variances, flags and status (draft, confirmed or settled), using cursor pagination. The optional status, meter_id and account_id query values filter the list. Requires the business:reconciliations:read permission.

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/metered-reconciliations" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Create metered reconciliation

Logs

POST /metered-reconciliations

Reconcile metered volume against reported sales and remitted cash

Creates a draft reconciliation for one meter and period: it reads the metered volume from the meter's readings (or uses metered_litres when no readings span the period), prices it with the reconciliation tariff active at period_end, and compares it with the reported volume, reported revenue and remitted cash. Differences beyond the tariff's tolerance raise flags. Returns 400 when the period is invalid, figures are negative, the meter has no active operator contract, no tariff covers the period, or no metered volume is available. Requires the business:reconciliations:write permission.

Returns

200 OK

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

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

OK

Get a metered reconciliation with variance flags

Logs

GET /metered-reconciliations/{id}

Returns one reconciliation with the metered and reported volumes, where the metered volume came from (meter_readings or entered), the expected, reported and remitted amounts, the variances and the flags raised. Returns 404 when it does not exist in the caller's tenant. Requires the business:reconciliations:read permission.

Returns

200 OK

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

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

OK

Confirm a metered reconciliation

Logs

POST /metered-reconciliations/{id}/confirm

Moves a draft reconciliation to confirmed, which makes it eligible for settlement, and returns the updated record. Returns 409 when the reconciliation is not in draft. Requires the business:reconciliations:settle permission.

Returns

200 OK

Permissions business:reconciliations:settle · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/metered-reconciliations/{id}/confirm" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Issue the reconciliation settlement statement

Logs

POST /metered-reconciliations/{id}/settle

Issues the settlement statement for a confirmed reconciliation: the commission is computed from the remitted amount and the contract's commission rate, the balance is the expected amount minus commission and remittance, and the reconciliation moves to settled. Returns the new settlement with 201. Returns 409 when the reconciliation is not confirmed, so a second call cannot issue a duplicate statement. Requires the business:reconciliations:settle permission.

Returns

200 OK

Permissions business:reconciliations:settle · Roles: admin, finance, owner

curl -X POST "$BUSINESS_API/metered-reconciliations/{id}/settle" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK