# Invoicing API

The Invoicing API manages customer invoices and recorded payments. Financial authorization, document state, and accounting-connection rules are enforced on every operation.

## Roles

| Operation | Member | Manager | Finance | HR |
|---|---:|---:|---:|---:|
| List and read invoices | No | Yes | Yes | No |
| Create or edit drafts | No | Yes | Yes | No |
| Send, void, or record payment | No | Yes | Yes | No |

A Manager-level license makes the Finance Role assignable; it does not grant Finance automatically. The API Client must explicitly have Finance or Manager.

## Invoice object

Money values are decimal strings with ISO 4217 currency codes; clients must not use binary floating-point arithmetic for totals.

```json
{
  "object": "invoice",
  "id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S",
  "number": "INV-1042",
  "status": "draft",
  "customer_id": "cus_01J8R4K4B2D0TQFM6VV93G6NQ8",
  "issue_date": "2026-08-22",
  "due_date": "2026-09-21",
  "currency": "USD",
  "lines": [
    {"id": "invl_01J8R6Q2P5", "description": "Implementation services", "quantity": "10", "unit_price": "250.00", "amount": "2500.00"}
  ],
  "subtotal": "2500.00",
  "tax_total": "0.00",
  "total": "2500.00",
  "amount_due": "2500.00",
  "version": 1,
  "created_at": "2026-08-22T09:00:00Z",
  "updated_at": "2026-08-22T09:00:00Z"
}
```

## List and create invoices

- `GET /v1/invoices` — `listInvoices`
- `POST /v1/invoices` — `createInvoice`, `Idempotency-Key`

Filters: `status`, `customer_id`, `issued_after`, `issued_before`, `due_after`, `due_before`, `currency`, `search`, `limit`, and `after`.

Creating an invoice creates a draft. Eos calculates line amounts and totals; client-supplied totals are rejected.

## Get and update an invoice

- `GET /v1/invoices/{invoice_id}` — `getInvoice`
- `PATCH /v1/invoices/{invoice_id}` — `updateInvoice`, `If-Match`
- `PUT /v1/invoices/{invoice_id}/lines` — `replaceInvoiceLines`, `If-Match`

Only a draft can be edited. Replacing lines is atomic: either the complete validated set is accepted or no line changes are applied.

## Send an invoice

`POST /v1/invoices/{invoice_id}/send`

Operation ID: `sendInvoice`. Required header: `Idempotency-Key`.

```json
{
  "delivery": {"email": true},
  "message": "Thank you for your business."
}
```

Eos validates customer delivery details and the configured financial workflow, generates the invoice PDF, and submits the email to the configured transactional provider before returning success. The invoice is then marked `sent`, and the state change is available by webhook. If the provider does not accept the message, the operation fails and the invoice remains a draft.

## Void an invoice

`POST /v1/invoices/{invoice_id}/void`

Operation ID: `voidInvoice`. Required header: `Idempotency-Key`.

Voiding follows the organization's workflow and connected accounting provider constraints. Issued invoices are not deleted.

## Record a payment

`POST /v1/payments`

Operation ID: `createPayment`. Required header: `Idempotency-Key`.

```json
{
  "invoice_id": "inv_01J8R6MB55Q2BEY9NE7NQE3J4S",
  "amount": "2500.00",
  "currency": "USD",
  "received_date": "2026-08-25",
  "method": "bank_transfer",
  "external_reference": "BANK-88201"
}
```

This records an externally received payment; it does not charge a payment method.

## Provider synchronization

If an invoice is synchronized to an organization-level accounting connection, the response includes provider-neutral sync status and external reference. The API never returns provider access tokens or bypasses the connection's configured permissions.

## Common errors

`INVOICE_NOT_FOUND`, `INVOICE_NOT_EDITABLE`, `INVALID_INVOICE_LINE`, `CURRENCY_MISMATCH`, `CUSTOMER_DELIVERY_DETAILS_MISSING`, `ACCOUNTING_CONNECTION_NOT_READY`, `PAYMENT_EXCEEDS_AMOUNT_DUE`, `STALE_RESOURCE`, and `WORKFLOW_BLOCKED`.

Next: [Files API](files.html).