---
title: "Create Invoice From Hours"
method: POST
path: "/api/v1/invoices/from-hours"
tags: ["invoices", "invoices"]
---

# Create Invoice From Hours

`POST /api/v1/invoices/from-hours`

## Request

- Base URL: `https://api.peil.app` (the document declares no server; this is the origin it was published from)
- URL: `https://api.peil.app/api/v1/invoices/from-hours`
- Auth: none declared

Compose a DRAFT invoice from unbilled hours for a client + period.

The agent-natural intent verb: gathers unbilled billable entries, builds
line items (summary | by_project | per_day), creates a draft, and links
the entries. Never sends — sending is a separate, separately-scoped call.

## Request body

- InvoiceFromHoursRequest: Composed intent verb: draft an invoice from unbilled hours (Builder API).
  - `client_id` integer, required
  - `period_start` string, date, required
  - `period_end` string, date, required
  - `grouping` 'summary' | 'by_project' | 'per_day'
  - `entry_ids` integer[], nullable
  - `notes` string, nullable
  - `reverse_charge` boolean

## Response `201`

Successful Response

- InvoiceFromHoursResponse
  - `invoice` Invoice, required
    - `invoice_number` string, nullable
    - `client_id` integer, required
    - `project_id` integer, nullable
    - `invoice_date` string, date, nullable
    - `period_start` string, date, nullable
    - `period_end` string, date, nullable
    - `due_date` string, date, nullable
    - `subtotal` number, nullable
    - `vat_rate` number, nullable
    - `vat_amount` number, nullable
    - `total_amount` number, nullable
    - `total_hours` number, nullable
    - `reverse_charge` boolean, nullable
    - `status` string
    - `payment_date` string, date, nullable
    - `notes` string, nullable
    - `pdf_path` string, nullable
    - `recurring` boolean, nullable
    - `recurrence_interval` string, nullable
    - `recurrence_anchor_day` integer, nullable
    - `recurrence_project_id` integer, nullable
    - `parent_invoice_id` integer, nullable
    - `email_sent_at` string, date-time, nullable
    - `resend_email_id` string, nullable
    - `email_delivered_at` string, date-time, nullable
    - `email_opened_at` string, date-time, nullable
    - `email_bounced_at` string, date-time, nullable
    - `email_failed_at` string, date-time, nullable
    - `payment_reference` string, nullable
    - `last_reminder_at` string, date-time, nullable
    - `reminder_count` integer
    - `scheduled_send_at` string, date-time, nullable
    - `template_fields` object, nullable
    - `id` integer, required
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `lines` InvoiceLineRead[]
      - `id` integer, required
      - `invoice_id` integer, required
      - `description` string, required
      - `hours` number, nullable
      - `rate` number, nullable
      - `amount` number, required
      - `sort_order` integer
    - `time_entry_ids` integer[]
  - `entry_count` integer, required
  - `total_hours` number, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/peil/apis/peil-api.md) · [All operations](https://skmtc.dev/peil/apis/peil-api/llms.txt) · [OpenAPI document](https://skmtc.dev/peil/apis/peil-api/revisions/ee3ca1246dde?raw)