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

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.

{
  "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.

{
  "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.

{
  "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.