Kiipu · invoicing v1 read-only
kiipu.
Reads how much ONE client named by name owes in total, as the ledger has it, and their next installment due. A client never invoiced comes back as never_invoiced, never as up to date; a lead or a churned client, as not_a_client. With several matches it refuses with ambiguous; with none, not_found.
Last updated
POST /api/v1/reads/kiipu.client_balance_get- Token scope
kiipu.client_balance_get@1- Workspace permission
api.kiipu.client_balance_getoff by default- Who reads
- The person behind the token, with their role. Someone who leaves the workspace stops reading.
Three permissions
A token with that scope, the workspace owner having switched the read on, and the person's role seeing it in the product. None of them is enough alone. OAuth only →
Request
| field | type | rules | |
|---|---|---|---|
client | string | required | min 1 · max 200 |
Response — output when status is done
| field | type | rules | |
|---|---|---|---|
client | string | required | |
standing | "owes" | "up_to_date" | "never_invoiced" | "not_a_client" | required | |
outstandingTotal | string | null | required | |
currency | string | null | required | |
nextInstallment | object | null | required |
nextInstallment
| field | type | rules | |
|---|---|---|---|
dueOn | string | required | ^\d{4}-\d{2}-\d{2}$ |
amount | string | required | ^-?\d+\.\d{2}$ |
Example
# Reads take an OAuth access token, not an API key, and no idempotency key: reading changes nothing.
curl -X POST https://niiko.org/api/v1/reads/kiipu.client_balance_get \
-H "Authorization: Bearer $NIIKO_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"client": "…"
}'
# 200 → done · 4xx → refused, with a named reasonWhy it may refuse
Each reason names who can fix it and how; detail.message, when present, says what to do. Refusals & HTTP codes →
invalid_inputrole_forbiddengrant_offreads_need_a_personambiguousnot_found
In the clients
| @vorluno/niiko-sdk | niiko.getClientBalance() |
| niiko (Python) | niiko.get_client_balance() from 0.4.0 · not on the registry yet |
| niiko-cli | niiko read kiipu.client_balance_get |
| n8n-nodes-niiko | No reads: the node holds a key, and reading needs a person through OAuth. |
| niiko-mcp-server | kiipu_client_balance_get readOnlyHint |