Leak allowances

Base URL: $CONSUMER_API

The object

invoice_idstring · required
eligibleboolean · required
reason_codestring · optional

Stable refusal code for an ineligible invoice; clients translate the value.

one of policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold, no_credit_value

consumption_m3number · required
historic_avg_m3number · optional
excess_m3number · optional
excess_value_centsinteger (int64) · optional
proposed_credit_centsinteger (int64) · optional
currencystring · optional
require_proofboolean · required
The object
{
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "eligible": true,
  "reason_code": "policy_disabled",
  "consumption_m3": 13.42,
  "historic_avg_m3": 1,
  "excess_m3": 1,
  "excess_value_cents": 1342,
  "proposed_credit_cents": 1,
  "currency": "MZN",
  "require_proof": true
}

Check an invoice against the leak allowance policy

Logs

POST /leak-allowances/assess

Checks whether an invoice of a linked account qualifies for a leak allowance without saving anything. The result says whether it is eligible, why not (for example the policy is disabled, the invoice is closed, the repair window or cooldown applies, or there is not enough history), and the historic average, excess consumption and proposed credit. invoice_id is required; an invoice outside the caller's scope returns 404.

Returns

200 OK

Show attributes
invoice_idstring · required
eligibleboolean · required
reason_codestring · optional

Stable refusal code for an ineligible invoice; clients translate the value.

one of policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold, no_credit_value

consumption_m3number · required
historic_avg_m3number · optional
excess_m3number · optional
excess_value_centsinteger (int64) · optional
proposed_credit_centsinteger (int64) · optional
currencystring · optional
require_proofboolean · required

Errors 400

curl -X POST "$CONSUMER_API/leak-allowances/assess" \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{}'
Response 200
{
  "invoice_id": "inv_2jnourvAGxXMMd5IyFbwc1LqUX1",
  "eligible": true,
  "reason_code": "policy_disabled",
  "consumption_m3": 13.42,
  "historic_avg_m3": 1,
  "excess_m3": 1,
  "excess_value_cents": 1342,
  "proposed_credit_cents": 1,
  "currency": "MZN",
  "require_proof": true
}

List the consumer's leak allowance applications

Logs

GET /leak-allowances

Pages the leak allowance applications on accounts linked to the caller, across tenants unless X-Tenant-ID selects one. An empty page is returned when the caller has no eligible account. Pagination uses limit and after.

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

curl -X GET "$CONSUMER_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Apply with proof of repair

Logs

POST /leak-allowances

Apply with proof of repair (multipart: invoice_id, description, proof)

Applies for a leak allowance (a credit for excess consumption caused by a leak) on an invoice of a linked account, sent as multipart/form-data with invoice_id, an optional description and an optional proof file (PDF, JPEG or PNG). The invoice is assessed against the tenant's policy first; an ineligible invoice returns 400 LEAK_ALLOWANCE_INELIGIBLE, a missing proof when the policy requires one returns 400, and an invoice that already has an open application returns 409. On success the application is created in submitted status with the proposed credit for staff review.

Returns

200 OK

curl -X POST "$CONSUMER_API/leak-allowances" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK

Get an application

Logs

GET /leak-allowances/{id}

Returns one leak allowance application, with its status, assessment figures and decision, when it belongs to an account linked to the caller. Applications outside the caller's scope return 404.

Returns

200 OK

curl -X GET "$CONSUMER_API/leak-allowances/{id}" \
  -H "Authorization: Bearer sk_test_..."
Response 200

OK