Skip to content
Hoursmith Docs
APIReferenceInvoices

Preview an invoice or reminder email

Preview an invoice or reminder email. Read-only. Renders the final subject and plain-text body the client would receive (private invoice link and bank details replaced by placeholders), the sender, attachments, default recipients, every address on file for the client, and readyToSend + problems. Nothing is minted or written. Read scope; Owner/Admin/Manager.

GET
/invoices/{id}/email-preview

Authorization

BearerAuth
AuthorizationBearer <token>

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

In: header

Path Parameters

id*string

Invoice id.

Query Parameters

type?string

Which email. Default invoice.

message?string

Optional personal note to render into the preview.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/invoices/497f6eca-6276-4993-bfeb-53cbbbba6f08/email-preview"
{  "data": {    "type": "invoice",    "invoice": {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "number": "string",      "clientId": "5e505642-9024-474d-9434-e5a44f505cc5",      "status": "DRAFT",      "paymentStatus": "unpaid",      "currency": "string",      "total": "string",      "amountPaid": "string",      "balanceDue": "string",      "issueDate": "2019-08-24",      "dueDate": "2019-08-24",      "sentAt": "2019-08-24T14:15:22Z",      "lastSentAt": "2019-08-24T14:15:22Z",      "paidAt": "2019-08-24T14:15:22Z"    },    "readyToSend": true,    "problems": [      "string"    ],    "marksInvoiceSent": true,    "from": {      "name": "string",      "email": "string"    },    "replyTo": "string",    "defaultRecipients": {      "to": [        "string"      ],      "cc": [        "string"      ]    },    "recipientOptions": [      {        "email": "string",        "name": "string",        "role": "string",        "source": "contact",        "isPrimary": true,        "isBillingDefault": true      }    ],    "subject": "string",    "text": "string",    "attachments": [      "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"  }}
Was this page helpful?

Correct a refunded paid 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. PAID invoices whose recorded principal is fully refunded only. Credits the invoice and creates an audited replacement DRAFT (201); if a correction already exists its replacement is returned (200, warning). The response includes correction.sourceInvoiceId and correction.reused. Counts toward the monthly invoice limit.

Email an invoice to its client

Emails the invoice PDF (and timesheet PDF when enabled) through the workspace's configured sender. A DRAFT becomes SENT atomically when the provider accepts the message; SENT/PAID invoices are re-sent unchanged; CANCELLED invoices are rejected (409). Every recipient must already be on file for the invoice's client (billing email, client email or a client contact); any other address is rejected with 422 — add it as a client contact in Hoursmith first. Omitted `to` uses the client's default billing recipient, exactly as the app pre-fills it. A provider failure returns 200 with status `failed` and `sendError`, and the invoice is unchanged. A NOT SENT warning means nothing was delivered. A NOT CONFIRMED warning means the provider call had started (a timeout, or an answer that came too late to record): the email may have reached the recipient, so check with them before sending again. Send and remind share the app's send budget: a one-minute cooldown per invoice (send and remind share it), 10 emails per invoice per UTC day, 30 per user per hour across workspaces, 20 per workspace per UTC day while it is on the Free plan or a trial and sends through the Hoursmith sender, and 100 per workspace per hour. A spent budget is a 429 and nothing is sent. Write scope; Owner/Admin/Manager. Idempotency-Key required (a replay never re-sends).