Create a draft invoice
Create a draft 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. Creates a DRAFT only — nothing is sent or published. Call POST /invoices/preview first. selectedEntryIds is required; omitted header fields use the in-app defaults listed on InvoiceCreate. Bill-to and line rates are frozen. Billed time entries and expenses are locked to the draft. Requested expenses that are not this client's are not billed and are listed in warnings. Counts toward the plan's monthly invoice limit (402 forbidden_plan when reached).
Authorization
BearerAuth Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.
In: header
Header Parameters
Caller-generated UUID/ULID; a retry with the same key and body replays the stored response.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Creates a DRAFT. selectedEntryIds is required (use [] for no tracked time). excludedEntryIds, from and to are rejected.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/invoices" \ -H "Idempotency-Key: string" \ -H "Content-Type: application/json" \ -d '{ "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "selectedEntryIds": [ "ee27e6bf-496d-4836-8009-874d6a5da3e7" ] }'{ "data": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "orgId": "25b2c2d5-a7fc-47d0-89e4-8709a1560bfa", "clientId": "5e505642-9024-474d-9434-e5a44f505cc5", "number": "string", "status": "DRAFT", "paymentStatus": "unpaid", "subtotal": "string", "discountAmount": "string", "taxRate": "string", "total": "string", "amountPaid": "string", "currency": "string", "notes": "string", "billToName": "string", "issueDate": "2019-08-24", "dueDate": "2019-08-24", "sentAt": "2019-08-24T14:15:22Z", "paidAt": "2019-08-24T14:15:22Z", "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "deletedAt": "2019-08-24T14:15:22Z", "balanceDue": "string", "paymentMethods": {}, "billToAddress": "string", "billToTaxNumber": "string", "poNumber": "string", "lastSentAt": "2019-08-24T14:15:22Z", "viewCount": 0, "lastViewedAt": "2019-08-24T14:15:22Z", "groupBy": "project", "timeRounding": "entry_15m", "showProjectName": true, "showTaskName": true, "attachTimesheet": true, "includeExpenseReceipts": true, "reminderOffsets": [ 0 ], "lineItems": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "position": 0, "kind": "time", "sourceType": "TRACKED_TIME", "description": "string", "subtitle": "string", "detail": "string", "groupLabel": "string", "quantity": "string", "unitLabel": "string", "unitPrice": "string", "amount": "string", "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", "expenseId": "a2142719-090a-410b-ad70-ea5efeb1c9dc" } ], "lineItemCount": 0, "draftLineSet": { "selectedEntryIds": [ "ee27e6bf-496d-4836-8009-874d6a5da3e7" ], "expenseIds": [ "4e1e9976-0015-4c46-b3e7-b9d93419b799" ], "manualLineItems": [ { "description": "string", "projectName": "string", "taskName": "string", "quantity": "string", "unitPrice": "string", "unitLabel": "string", "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8" } ], "fixedFeeAllocations": [ { "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8", "amount": "string" } ] }, "draftLineSetComplete": true }, "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" }}{ "error": { "code": "unauthenticated", "message": "string", "fields": { "property1": "string", "property2": "string" }, "requiredPlan": "studio", "feature": "string", "requestId": "string" }}List invoices
Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Lists invoices; each row includes balanceDue. Create drafts with POST /invoices.
Get one invoice
Owner, Admin or Manager only (Member tokens receive 403 forbidden_scope). The API itself requires the Studio or Agency plan. Returns the frozen snapshot with lineItems; DRAFT invoices also include draftLineSet (the exact line set PATCH accepts).