# Invoices

> Finalised invoices: create, read and list them.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List invoices

`GET /api/public/v1/invoices`

SDK: `prosaic.invoices.list(params)`

Returns invoices in the active workspace that the authenticated user can
access. Results are paginated and can be narrowed by client or entity.
When both filters are supplied, an invoice must match both.

### Query parameters

- `entityId` (string): Return invoices for one entity.
- `clientId` (string): Return invoices whose entity is associated with this client user.
- `status` (string): Filter by persisted invoice lifecycle status. One of: `DRAFT`, `FINALISED`, `PAID`, `VOIDED`.
- `updatedSince` (string): Return invoices updated on or after this ISO 8601 timestamp.
- `page` (integer): Default: `1`.
- `pageSize` (integer): Default: `20`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `workspaceId` (string, required)
    - `fileId` (string, nullable, required)
    - `invoiceNumber` (string, nullable, required)
    - `status` (string, required)
    - `taxMode` (string, required)
    - `issueDate` (string, date-time, required)
    - `dueDate` (string, date-time, nullable, required)
    - `sentAt` (string, date-time, nullable, required)
    - `recipientName` (string, required)
    - `recipientEmail` (string, nullable, required)
    - `recipientAddress` (string, nullable, required)
    - `bankAccountId` (string, nullable, required)
    - `bankAccountName` (string, nullable, required)
    - `subtotal` (number, required)
    - `taxTotal` (number, required)
    - `total` (number, required)
    - `amountDue` (number, nullable, required)
    - `notes` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `lines` (array of objects, required)
      - `id` (string, required)
      - `description` (string, required)
      - `quantity` (number, required)
      - `unitPrice` (number, required)
      - `taxRate` (number, required)
      - `taxRateCode` (string, nullable, required)
      - `entityAccountId` (string, nullable, required)
      - `amount` (number, required)
      - `taxAmount` (number, required)
      - `position` (number, required)
  - `pagination` (object, required)
    - `currentPage` (number, required)
    - `pageSize` (number, required)
    - `totalCount` (number, required)
    - `totalPages` (number, required)
    - `hasNextPage` (boolean, required)
    - `hasPreviousPage` (boolean, required)
- `400`: Invalid query parameters.
- `401`: Unauthorized.
- `403`: Insufficient role.
- `404`: Workspace not found.
- `500`: Internal server error.

### Example (Node SDK)

```ts
const page = await prosaic.invoices.list();
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/invoices \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Get an invoice by ID for an entity

`GET /api/public/v1/entities/{entityId}/invoices/{invoiceId}`

SDK: `prosaic.invoices.retrieve(entityId, invoiceId)`

### Path parameters

- `entityId` (string, required)
- `invoiceId` (string, required)

### Responses

- `200`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `workspaceId` (string, required)
    - `fileId` (string, nullable, required)
    - `invoiceNumber` (string, nullable, required)
    - `status` (string, required)
    - `taxMode` (string, required)
    - `issueDate` (string, date-time, required)
    - `dueDate` (string, date-time, nullable, required)
    - `sentAt` (string, date-time, nullable, required)
    - `recipientName` (string, required)
    - `recipientEmail` (string, nullable, required)
    - `recipientAddress` (string, nullable, required)
    - `bankAccountId` (string, nullable, required)
    - `bankAccountName` (string, nullable, required)
    - `subtotal` (number, required)
    - `taxTotal` (number, required)
    - `total` (number, required)
    - `amountDue` (number, nullable, required)
    - `notes` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `lines` (array of objects, required)
      - `id` (string, required)
      - `description` (string, required)
      - `quantity` (number, required)
      - `unitPrice` (number, required)
      - `taxRate` (number, required)
      - `taxRateCode` (string, nullable, required)
      - `entityAccountId` (string, nullable, required)
      - `amount` (number, required)
      - `taxAmount` (number, required)
      - `position` (number, required)
- `400`: Invalid invoice ID.
- `401`: Unauthorized.
- `404`: Invoice, entity, or workspace not found.
- `500`: Internal server error.

### Example (Node SDK)

```ts
const { data } = await prosaic.invoices.retrieve(entityId, invoiceId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices/$INVOICE_ID \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Create a finalised invoice

`POST /api/public/v1/entities/{entityId}/invoices`

SDK: `prosaic.invoices.create(entityId, params)`

Creates a complete, finalised invoice for the specified entity. The
entity is taken from the URL; `status` cannot be supplied. Finalised
invoices are not automatically delivered to the recipient.

Where the workspace records invoices as receivables (accrual
accounting), finalising posts the invoice to the ledger, which needs a
`contactId`. Without one the request is refused with 409
`INVOICE_NOT_EDITABLE` and nothing is created.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `application/json`

- `taxMode` (string, required): One of: `NO_TAX`, `TAX_INCLUSIVE`, `TAX_EXCLUSIVE`.
- `issueDate` (string, required)
- `recipientName` (string, required)
- `lines` (array of objects, required)
  - `description` (string, required)
  - `quantity` (string, required)
  - `unitPrice` (string, required)
  - `taxRateCode` (string, required)
  - `entityAccountId` (string, required)
  - `taxRate` (string)
- `bankAccountId` (string, nullable)
- `notes` (string, nullable)
- `contactId` (string, nullable)
- `dueDate` (string, nullable)
- `bankAccountName` (string, nullable)
- `invoiceNumber` (string)
- `recipientEmail` (string, nullable)
- `recipientAddress` (string, nullable)
- `recipientEmails` (array of strings)

### Responses

- `201`: Successful response
  - `data` (object, required)
    - `id` (string, required)
    - `entityId` (string, required)
    - `workspaceId` (string, required)
    - `fileId` (string, nullable, required)
    - `invoiceNumber` (string, nullable, required)
    - `status` (string, required)
    - `taxMode` (string, required)
    - `issueDate` (string, date-time, required)
    - `dueDate` (string, date-time, nullable, required)
    - `sentAt` (string, date-time, nullable, required)
    - `recipientName` (string, required)
    - `recipientEmail` (string, nullable, required)
    - `recipientAddress` (string, nullable, required)
    - `bankAccountId` (string, nullable, required)
    - `bankAccountName` (string, nullable, required)
    - `subtotal` (number, required)
    - `taxTotal` (number, required)
    - `total` (number, required)
    - `amountDue` (number, nullable, required)
    - `notes` (string, nullable, required)
    - `createdAt` (string, date-time, required)
    - `updatedAt` (string, date-time, required)
    - `lines` (array of objects, required)
      - `id` (string, required)
      - `description` (string, required)
      - `quantity` (number, required)
      - `unitPrice` (number, required)
      - `taxRate` (number, required)
      - `taxRateCode` (string, nullable, required)
      - `entityAccountId` (string, nullable, required)
      - `amount` (number, required)
      - `taxAmount` (number, required)
      - `position` (number, required)
- `400`: Invalid request or invoice input, or system account setup is missing or invalid (SYSTEM_ACCOUNT_VALIDATION).
- `401`: Unauthorized.
- `404`: Entity or workspace not found.
- `409`: The invoice can't be finalised, for example it has no contact where the workspace uses accrual accounting.
- `500`: Invoice creation failed.

### Example (Node SDK)

```ts
const { data } = await prosaic.invoices.create(entityId, {
  taxMode: 'NO_TAX',
  issueDate: '2026-04-01',
  recipientName: 'Example Ltd',
  lines: [
    {
      description: 'Office supplies',
      quantity: '1',
      unitPrice: '100.00',
      taxRateCode: 'TAX_RATE_CODE',
      entityAccountId: 'ENTITY_ACCOUNT_ID',
    },
  ],
});
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/invoices \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taxMode": "NO_TAX",
    "issueDate": "2026-04-01",
    "recipientName": "Example Ltd",
    "lines": [
      {
        "description": "Office supplies",
        "quantity": "1",
        "unitPrice": "100.00",
        "taxRateCode": "TAX_RATE_CODE",
        "entityAccountId": "ENTITY_ACCOUNT_ID"
      }
    ]
  }'
```