Skip to content
Hoursmith Docs
APIReferenceInvoices

Preview an invoice (dry run)

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.

POST
/invoices/preview

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/invoices/preview" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "clientId": "5e505642-9024-474d-9434-e5a44f505cc5"  }'
{  "data": {    "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",    "clientName": "string",    "currency": "string",    "advisoryNumber": "string",    "issueDate": "2019-08-24",    "dueDate": "2019-08-24",    "taxRate": "string",    "discountAmount": "string",    "notes": "string",    "poNumber": "string",    "groupBy": "string",    "showProjectName": true,    "showTaskName": true,    "timeRounding": "string",    "attachTimesheet": true,    "includeExpenseReceipts": true,    "selectionMode": "explicit",    "selectedEntryIds": [      "ee27e6bf-496d-4836-8009-874d6a5da3e7"    ],    "unavailableEntryIds": [      "84a22e2c-9722-4766-93e2-4bef24e67888"    ],    "expenseIds": [      "4e1e9976-0015-4c46-b3e7-b9d93419b799"    ],    "skippedExpenses": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "reason": "string"      }    ],    "billableEntries": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "entryDate": "2019-08-24",        "userId": "2c4a230c-5085-4924-a3e1-25fb4fc5965b",        "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",        "projectName": "string",        "taskId": "e6e9d88a-9b63-468a-aec3-b7a11de27af8",        "taskName": "string",        "note": "string",        "durationSeconds": 0,        "hourlyRate": "string",        "roundedHours": "string",        "estimatedAmount": "string",        "selected": true      }    ],    "billableEntryCount": 0,    "billableExpenses": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "expenseDate": "2019-08-24",        "description": "string",        "category": "string",        "amount": "string",        "currency": "string",        "projectId": "5a8591dd-4039-49df-9202-96385ba3eff8",        "selected": true      }    ],    "billableExpenseCount": 0,    "fixedFeeProjects": [      {        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",        "projectName": "string",        "fixedFeeAmount": "string",        "priorInvoicedAmount": "string",        "draftReservedAmount": "string",        "invoicedAmount": "string",        "remainingAmount": "string",        "currentInvoiceAmount": "string",        "initialized": true      }    ],    "invoice": {      "lineCount": 0,      "lines": [        {          "position": 0,          "sourceType": "string",          "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"        }      ],      "subtotal": "string",      "discountAmount": "string",      "taxRate": "string",      "tax": "string",      "total": "string"    },    "canCreate": true,    "blockingIssues": [      "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"  }}
Was this page helpful?