Invoices API
List, create, update, summarize, and manage recurring invoices through public API v1.
Invoice operations use invoices.read or invoices.write. Eigenn scopes every invoice operation to the authenticated team.
Invoice Endpoints
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /invoices | invoices.read | List and filter invoices |
| POST | /invoices | invoices.write | Create, create and send, or schedule an invoice |
| GET | /invoices/payment-status | invoices.read | Read paginated payment status |
| GET | /invoices/summary | invoices.read | Summarize selected invoice statuses |
| GET | /invoices/{id} | invoices.read | Retrieve one invoice |
| PUT | /invoices/{id} | invoices.write | Update status, paid time, or internal note |
| DELETE | /invoices/{id} | invoices.write | Delete a draft or canceled invoice |
There is no separate public POST /invoices/{id}/send operation. You set the email behavior with deliveryType when you create the invoice.
List Invoices
GET /invoices supports cursor pagination with pageSize from 1 to 100.
Filters include:
- Search text
- Customer IDs
- Invoice statuses
- Issue, due, and sent date ranges
- Amount, tax, and VAT ranges
- Recurring state or series IDs
- Sort tuple
curl --request GET \
--url "https://api.eigenn.io/v1/invoices?pageSize=25" \
--header "Authorization: Bearer $EIGENN_API_TOKEN"The returned records can include calculated totals, customer details, status dates, and PDF or preview URLs when a token exists.
Create an Invoice
POST /invoices needs:
- customerId
- deliveryType
- dueDate
- issueDate
- template
deliveryType accepts:
| Value | Result |
|---|---|
| create | Finalize immediately as unpaid without the send action |
| create_and_send | Finalize as unpaid and start customer email delivery |
| scheduled | Schedule future work at scheduledAt |
scheduledAt must be in the future for scheduled delivery. If you do not supply invoiceNumber, Eigenn generates the next sequential number. If you supply a number that is already in use, Eigenn returns 409.
Use the OpenAPI explorer or the generated SDK model for the complete template and line-item structure. Do not send UI form state that the request schema does not contain.
The creation response returns the ID, the status, timestamps, and PDF or preview URLs when they are available. Delivery can continue after Eigenn finalizes the invoice. An unpaid response alone does not prove that the email is complete.
Retrieve and Update
GET /invoices/{id} can include recurring information when you request includeRecurring.
PUT /invoices/{id} accepts:
- internalNote
- paidAt
- status
Eigenn documents these status values: paid, canceled, unpaid, scheduled, and draft. This endpoint is not a general replacement for the full payload that creates an invoice.
Delete
DELETE /invoices/{id} applies only to draft and canceled invoices. Cancel an eligible non-draft invoice before you delete it.
When you delete an invoice, you do not delete its customer.
Summary and Payment Status
GET /invoices/summary accepts one or more statuses.
GET /invoices/payment-status supports cursor pagination and pageSize from 1 to 100. Use these operations for status views. Do not recalculate every aggregate from a partial invoice page.
Recurring Invoice Endpoints
| Method | Endpoint | Scope | Purpose |
|---|---|---|---|
| GET | /invoice-recurring | invoices.read | List recurring series |
| POST | /invoice-recurring | invoices.write | Create a series |
| GET | /invoice-recurring/{id} | invoices.read | Retrieve a series |
| PUT | /invoice-recurring/{id} | invoices.write | Update a series |
| DELETE | /invoice-recurring/{id} | invoices.write | Delete a series |
| POST | /invoice-recurring/{id}/pause | invoices.write | Pause generation |
| POST | /invoice-recurring/{id}/resume | invoices.write | Resume generation |
| GET | /invoice-recurring/{id}/upcoming | invoices.read | Preview the next invoices |
When you delete a recurring series, Eigenn cancels the future scheduled work and returns the scheduled invoices to draft. The invoices that Eigenn generated before remain independent records.
When you pause a series, Eigenn stops future generation and returns the already scheduled invoices to draft. You can resume only a paused series.
Idempotency
Authenticated invoice writes accept an optional Idempotency-Key of at most 128 characters.
Use a stable key for one logical create or update. This is important when you do not know the network outcome. If you repeat create_and_send without replay protection, Eigenn can duplicate work for the customer.
Common Errors
| Status | Cause |
|---|---|
| 400 | Invalid schedule, invoice number, status, or deletion state |
| 401 | Missing or invalid bearer token |
| 403 | Missing invoices.read or invoices.write |
| 404 | Invoice or customer not found in the team |
| 409 | Invoice number or current state conflict |
| 422 | Request structure is invalid |
| 429 | Resource limit exceeded |