Skip to content
Hoursmith Docs
APIReferenceInvoices

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).

POST
/invoices

Authorization

BearerAuth
AuthorizationBearer <token>

Personal Access Token. Mint at Settings → API. Token shape: hsk_<env>_<prefix12>_<secret32>.

In: header

Header Parameters

Idempotency-Key*string

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"  }}
Was this page helpful?