Time and expensesInvoice unbilled time

Time and expenses

Invoice unbilled time

POST/v1/documents/from-unbilled

Coming April 2027

This endpoint ships in April 2027. The shape shown here can still change before release.

Creates a draft invoice for a client from their unbilled time and billable expenses.

Unbilled billable time for the client is grouped by project tag or by day into invoice lines, each priced as time times rate. Billable expenses for the client are added with their markup. The time entries and expenses are then linked to the invoice and locked, so the same work is never billed twice.

The invoice is a draft: check it and send it with Send a document. AI automations such as "invoice Client X for last week's time" use this capability. This is also the MCP tool invoice_unbilled. See Time tracking and Expenses.

Creates a draft. Sending is a separate, confirmed call.

Permission: documents.create
Type: Write. Creates or changes data and writes an audit entry.
Auth: API key, MCP token or signed-in session
Capability: invoice_unbilled
MCP tool: invoice_unbilled
CLI: freeinvoiceautomation invoice unbilled
Available: From April 2027

invoice_unbilled

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/from-unbilled \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "0193f2a0-5b1c-7d2e-8f3a-4b5c6d7e8f90",
  "group_by": "project"
}'

{
  "data": {
    "id": "0193fa10-8a9b-7c0d-8e1f-2a3b4c5d6e7f",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "client_id": "0193f2a0-5b1c-7d2e-8f3a-4b5c6d7e8f90",
    "type": "invoice",
    "status": "draft",
    "number": null,
    "currency": "USD",
    "subtotal_minor": "17890",
    "tax_minor": "0",
    "total_minor": "17890"
  }
}

Authorizations

Authorizationstringrequired

Bearer <api-key>. An API key from Settings > API keys, or an MCP token. See Authentication.

Headers

Idempotency-Keystringrequired

Required for API key and MCP calls on creates. A retry with the same key never creates a second record. See Idempotency.

Body

application/json

business_idstring<uuid>

Business that issues the invoice.

client_idstring<uuid>required

Client to invoice.

group_byenum<string>

Group time into lines by project tag or by day. Defaults to the business setting (project).

Available options: project, day

Response

201 - application/json

idstring<uuid>

Id of the new draft invoice.

business_idstring<uuid>

The business.

client_idstring<uuid>

The client.

typestring

Always invoice.

statusstring

Always draft.

numberstring | null

null: a draft gets its number when it is first sent.

currencystring

Invoice currency.

subtotal_minorstring

Sum of the lines before tax.

tax_minorstring

Tax.

total_minorstring

Invoice total.

Errors

validation_failed

idempotency_key_reused

business_out_of_scope

Plus the common errors every call can return. See Errors.

Suggest edits Raise issue

List unbilled timePrevious Record an expenseNext

invoice_unbilled

curl --request POST \
  --url https://api.freeinvoiceautomation.com/v1/documents/from-unbilled \
  --header 'Authorization: Bearer <api-key>' \
  --header 'Idempotency-Key: <unique-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "client_id": "0193f2a0-5b1c-7d2e-8f3a-4b5c6d7e8f90",
  "group_by": "project"
}'

{
  "data": {
    "id": "0193fa10-8a9b-7c0d-8e1f-2a3b4c5d6e7f",
    "business_id": "0193f29e-11aa-7c3b-8d2e-5a6b7c8d9e0f",
    "client_id": "0193f2a0-5b1c-7d2e-8f3a-4b5c6d7e8f90",
    "type": "invoice",
    "status": "draft",
    "number": null,
    "currency": "USD",
    "subtotal_minor": "17890",
    "tax_minor": "0",
    "total_minor": "17890"
  }
}