Clients ready to invoice
Clients ready to invoice. Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Read scope. Clients with unbilled billable time (stopped entries; running timers are left out), expenses or fixed-fee balance; one currency per row. Rows are ordered by the raw estimate compared as a plain number across currencies (no conversion) and then cut to `limit`, so a large amount in a low-value currency (for example JPY) can push workspace-currency clients out of a small page: pass clientId or a larger limit. Amounts are estimates — preview for exact totals.
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Query Parameters
Repeatable; at most 25.
Default 10.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/invoices/ready-to-invoice"{ "data": [ { "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "clientName": "string", "currency": "string", "unbilledSeconds": 0, "unbilledHours": "string", "timeAmount": "string", "expenseAmount": "string", "expenseCount": 0, "fixedFeeAmount": "string", "fixedProjectCount": 0, "estimatedTotal": "string" } ], "warnings": [ "string" ]}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}Preview an invoice (dry run)
Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Requires only read scope; never persists anything (runs the real draft writer in a rolled-back transaction). Same body as POST /invoices with everything optional except clientId, plus from/to. Returns billable sources, the exact lines and totals, an advisory number, and blockingIssues when the draft cannot be created. Like every POST it takes an Idempotency-Key; reusing a key with the same body replays the stored preview, so use a new key to see fresh data.
Cancel an invoice
Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Requires write scope and an Idempotency-Key. Unpaid DRAFT or SENT only. Releases time entries and expenses, deletes receipt attachments, revokes the public invoice/payment link and clears sent/view history; the number stays retired. Already cancelled: returned unchanged with a warning. Sends no email.