Invoices API

Summary

Invoice operations use invoices.read or invoices.write. Eigenn scopes every invoice operation to the authenticated team.

Capabilities

Invoice Endpoints

There is no separate public POST /invoices/{id}/send operation. You set the email behavior with deliveryType when you create the invoice.

Prerequisites

You must have a valid bearer token with the invoices.read and/or invoices.write scope. Ensure you are operating within an authenticated team context. Customers must exist in your team before you can issue invoices to them.

Concepts

Invoices represent individual or recurring requests for payment. Each invoice is tied to a customer and can have various statuses such as unpaid, paid, draft, scheduled, or canceled. Recurring invoice series automate the creation of invoices on a set schedule, and generated invoices remain as separate records if the series is paused or deleted. Invoice creation can include sending or scheduling email delivery. Idempotency keys provide bounded replay protection for successful writes; inspect invoice state after a failed or uncertain request.

Workflow

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:

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. Amounts and line prices use major currency units, such as 125.50, rather than payment-provider minor units. Line-item names and rich-text fields use the documented editor-content structures; returned content fields can be serialized JSON strings.

The create schema accepts a line item's productId, but the current creation handler does not retain that link. Do not rely on API-created invoices for catalog-product or variant revenue attribution.

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.

A failed create request can still leave an invoice: the draft is stored before future-schedule validation and delivery queueing. Validate the schedule before submitting, use a stable invoice number for reconciliation, and inspect the team's existing invoices before retrying an error. Error responses are not cached for idempotent replay.

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.

Changing status does not collect money, create a payment record, or manage delivery jobs. Supply paidAt when marking an invoice paid and explicitly clear it with null when reopening it. Setting status: "scheduled" here does not schedule delivery; use scheduled creation or the application's schedule controls.

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 optionally filters by statuses and returns a team total with currency breakdown information. Missing exchange rates fall back to 1:1; inspect the breakdown before treating a mixed-currency total as a converted accounting value.

GET /invoices/payment-status returns one team-level object with score and paymentStatus. It has no cursor pagination or page-size parameters and does not return individual payment records. Retrieve an invoice by ID to inspect that invoice's status.

Recurring Invoice Endpoints

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.

Behavior specification

Idempotency

Authenticated invoice writes accept an optional Idempotency-Key of at most 128 characters.

Use a stable key for one logical create or update. Successful responses are cached for 24 hours, scoped to the authenticated identity, method, path, query, and key. The request body is not part of that identity: use a new key for a different intended change, or the old response can be replayed.

A request still in progress can return 409 with Retry-After. An unavailable replay guard can return 503. Replay protection is not an exactly-once guarantee, particularly after errors or cache failures. Check the invoice before retrying an uncertain create-and-send request.

Common Errors

Diagrams

Screenshots

Not applicable: this page describes an API or a non-visual workflow rather than an application screen.

Verification

1. Authenticate with a bearer token and list invoices; expect filtered invoice data and metadata.
2. Create an invoice with valid data and deliveryType; expect a response with the invoice ID, status, and possible PDF/preview URLs.
3. Replay a successful creation with the same key and unchanged request within 24 hours; expect the cached response. For a failed request, inspect persisted invoices before any retry.
4. Request summary and payment-status endpoints; expect aggregate totals and a single team payment-health object, respectively. Inspect an individual invoice through its ID.
5. Create and then pause a recurring series; expect scheduled invoices moved to draft.
6. Attempt to delete an invoice that is not draft or canceled; expect an error response.
7. Attempt any invoice action without appropriate scope or a valid token; expect 401 or 403 error responses.

Related

Related Pages

• Invoices
• Create and Send Invoices
• Authentication
• Errors