evenbooks
Sign inStart for free

Invoices

Drafts, issuing, sending, PDFs and public links.

Paths are relative to https://evenbooks.org/api/v1. How keys, errors, paging and versions work is in the guide; the whole reference is also an OpenAPI 3.1 document.

Administrator key marks endpoints that need a key with the admin role, Write access those a read-only key can’t call, and Idempotent those that accept an idempotency key.

List invoices

get/invoices

Newest issue date first unless sort and dir say otherwise. outstanding keeps issued invoices that are not fully paid; overdue keeps those past their due date; q searches the number, memo and customer name. List items leave lines empty and omit allocations: get one invoice for those.

Parameters

Response 200

A page of InvoiceDto ({ items, nextCursor, total }, see paging).

Errors 400 · 401 · 403 · 404 · 409 · 429

Create a draft invoice

post/invoices
Write access

A draft has no number and is not in the books yet; issue it with POST /invoices/{id}/issue. The customer’s name, email and address are copied onto the invoice. dueDate defaults to issueDate plus termsDays (the company’s default terms when omitted), and memo and footer default to the invoice branding defaults.

Request body

CreateInvoiceInput

  • contactIdstring · Uuidrequired
  • issueDatestring · PlainDateStringrequired
  • dueDatestring · PlainDateString
  • termsDaysinteger

    0–365

  • linesarray of DocumentLineInputrequired

    1–200 items

    Show 7 fields of each item
  • documentDiscountDiscountInput or null
    Show 2 fields
  • memostring or null

    up to 2000 characters

  • footerstring or null

    up to 2000 characters

  • paymentUrlstring or null

    up to 2000 characters · pattern ^https:\/\/.*

  • onlinePaymentsDisabledboolean

Response 200

InvoiceDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Get an invoice

get/invoices/{id}

Includes its lines and its allocations (payments and credits applied to it).

Parameters

  • idstring (uuid)path · required

Response 200

InvoiceDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Change an invoice

patch/invoices/{id}
Write access

Send version from your last read (409 version_conflict if it changed). On a draft, any field of the create body can change, and lines, when sent, replace all lines. On an issued, paid or void invoice only paymentUrl and onlinePaymentsDisabled change; other fields are ignored.

Parameters

  • idstring (uuid)path · required

Request body

UpdateInvoiceInput

  • contactIdstring · Uuid
  • issueDatestring · PlainDateString
  • dueDatestring · PlainDateString
  • termsDaysinteger

    0–365

  • linesarray of DocumentLineInput

    1–200 items

    Show 7 fields of each item
  • documentDiscountDiscountInput or null
    Show 2 fields
  • memostring or null

    up to 2000 characters

  • footerstring or null

    up to 2000 characters

  • paymentUrlstring or null

    up to 2000 characters · pattern ^https:\/\/.*

  • onlinePaymentsDisabledboolean
  • versionintegerrequired

Response 200

InvoiceDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Delete a draft invoice

delete/invoices/{id}
Write access

Only drafts can be deleted (409 immutable otherwise). Void an issued invoice instead.

Parameters

  • idstring (uuid)path · required

Response 204

Done; no body

No body.

Errors 400 · 401 · 403 · 404 · 409 · 429

List emails of an invoice

get/invoices/{id}/emails

Every email queued for this invoice, newest first, with its delivery status.

Parameters

  • idstring (uuid)path · required

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Issue an invoice

post/invoices/{id}/issue
Write accessIdempotent

Turns a draft into a final invoice: gives it the next invoice number, posts it to the books (money the customer owes, against income and sales tax), creates its public link and queues its PDF. Send version from your last read (409 version_conflict); the total must be above zero, and a date in a locked period is refused (409 period_locked). issueDate replaces the draft’s date and recalculates the due date from the terms.

Parameters

  • idstring (uuid)path · required

Request body

IssueInvoiceInput

Response 200

InvoiceDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

List PDF versions of an invoice

get/invoices/{id}/pdf

Every PDF made for this invoice, newest first. Download one with GET /attachments/{attachmentId}/download.

Parameters

  • idstring (uuid)path · required

Response 200

Errors 400 · 401 · 403 · 404 · 409 · 429

Get or remake the invoice PDF

post/invoices/{id}/pdf
Write access

Returns the current PDF, making one first if the invoice has none. regenerate: true makes a new version with the design saved when the invoice was issued; applyCurrentDesign: true makes one with the current invoice branding and keeps that design for later PDFs. Drafts have no PDF (409 invalid_state). Download it with GET /attachments/{attachmentId}/download.

Parameters

  • idstring (uuid)path · required

Request body

PostInvoicesIdPdfBody

  • regenerateboolean

    default false

  • applyCurrentDesignboolean

    default false

Response 200

InvoicePdfDto

  • attachmentIdstring
  • downloadPathstring

    Path of the download: /api/v1/attachments/{attachmentId}/download for API keys (the app gets its own /api/... path).

Errors 400 · 401 · 403 · 404 · 409 · 429

Email an invoice

post/invoices/{id}/send
Write accessIdempotent

Queues an email to to with the invoice PDF attached; the server sends it shortly after. Only issued or paid invoices (409 invalid_state). subject and message replace the template’s; usePlatformSender sends from the Evenbooks address instead of the company’s own domain. Counts toward the company’s hourly and daily email limits (429 rate_limited). An address on the suppression list is recorded with status suppressed and not sent. Follow delivery with GET /invoices/{id}/emails.

Parameters

  • idstring (uuid)path · required

Request body

SendInvoiceEmailInput

  • tostring (email)required

    up to 254 characters

  • messagestring or null

    up to 5000 characters

  • subjectstring

    1–250 characters

  • usePlatformSenderboolean
  • idempotencyKeystring · IdempotencyKey

Response 200

EmailMessageDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Void an invoice

post/invoices/{id}/void
Write accessIdempotent

Cancels an issued invoice by posting a reversing entry on date (default: the issue date) and turns off its public link. Refused while payments or credits are applied to it (409 invalid_state): reverse those allocations first, or give a credit note instead. Needs version from your last read; refused in a locked period (409 period_locked). Delete a draft instead of voiding it.

Parameters

  • idstring (uuid)path · required

Request body

VoidInvoiceInput (fields under Schemas)

Response 200

InvoiceDto (fields under Schemas)

Errors 400 · 401 · 403 · 404 · 409 · 429

Issue or email many invoices

post/invoices/bulk
Write access

Up to 100 invoices, each with its own version and idempotencyKey: one failure (a stale version, a locked period, a missing email address) does not stop the others, and a retry with the same keys repeats only what did not go through. issue issues drafts; send emails issued invoices to the address on the invoice, or else the contact’s, and skips invoices with neither. The response has one result per invoice and the counts.

Request body

BulkInvoiceInput

One of these shapes:

action: "issue"

  • actionstringrequired

    Always "issue"

  • itemsarray of objectrequired

    1–100 items

    Show 3 fields of each item
    • idstring · Uuidrequired
    • versionintegerrequired
    • idempotencyKeystring · IdempotencyKeyrequired

action: "send"

  • actionstringrequired

    Always "send"

  • itemsarray of objectrequired

    1–100 items

    Show 3 fields of each item
    • idstring · Uuidrequired
    • versionintegerrequired
    • idempotencyKeystring · IdempotencyKeyrequired
  • messagestring or null

    up to 2000 characters

Response 200

BulkInvoiceResultDto

  • actionstring

    One of: issue send

  • resultsarray of BulkInvoiceItemResult
  • succeededinteger
  • failedinteger
  • skippedinteger

Errors 400 · 401 · 403 · 404 · 409 · 429

Calculate invoice totals

post/invoices/preview

Works out each line’s discount, sales tax and total, and the document totals, without saving anything. Credit notes use the same calculation.

Request body

PostInvoicesPreviewBody

Response 200

DocumentPreviewDto

Errors 400 · 401 · 403 · 404 · 409 · 429

Schemas

The types these endpoints take or return, by name. Type names above link here.

Address

  • line1stringoptional

    up to 200 characters

  • line2stringoptional

    up to 200 characters

  • citystringoptional

    up to 100 characters

  • regionstringoptional

    up to 100 characters

  • postalCodestringoptional

    up to 20 characters

  • countrystringoptional

    up to 2 characters

AllocationDto

  • idstring
  • sourceTypestring

    One of: payment credit_note

  • paymentIdstring or null
  • creditNoteIdstring or null
  • invoiceIdstring
  • invoiceNumberstring or nulloptional
  • amountstring · DecimalString
  • datestring · PlainDateString
  • statusstring

    One of: active reversed

  • journalEntryIdstring or null
  • reversalJournalEntryIdstring or null
  • sourceLabelstringoptional

BulkInvoiceItemResult

  • idstring
  • numberstring or null
  • okboolean
  • skippedbooleanoptional
  • invoiceInvoiceDtooptional
  • emailEmailMessageDtooptional
  • errorobjectoptional
    Show 2 fields
    • codestring
    • messagestring

CustomerSnapshotDto

  • namestring
  • emailstring or nulloptional
  • phonestring or nulloptional
  • addressAddressoptional

DecimalString

decimal string

string

up to 32 characters · pattern ^-?\d+(\.\d+)?$

Discount

DiscountInput

DocumentLineDto

DocumentLineInput

DocumentStatus

string

One of: draft issued paid void

EmailMessageDto

  • idstring
  • kindstring
  • invoiceIdstring or null
  • toEmailstring
  • fromEmailstring or nulloptional
  • replyTostring or nulloptional
  • templateVersionnumber or nulloptional
  • subjectstring
  • statusstring · EmailStatus

    One of: queued sending sent delivered bounced complained failed uncertain suppressed

  • providerMessageIdstring or null
  • attemptsinteger
  • lastErrorstring or null
  • isResendboolean
  • requestedBystring
  • queuedAtstring
  • sentAtstring or null
  • deliveredAtstring or null
  • failedAtstring or null

EmailStatus

string

One of: queued sending sent delivered bounced complained failed uncertain suppressed

IdempotencyKey

string

8–128 characters

InvoiceDto

InvoicePdfVersionDto

  • versioninteger
  • attachmentIdstring
  • reasonstring

    Why it was made: on_demand, manual, design_updated or email_snapshot.

  • createdAtstring
  • sha256string or null

LineTaxDto

NonNegativeDecimalString

string

up to 32 characters · pattern ^\d+(\.\d+)?$

PageCursor

string

up to 2000 characters

PlainDateString

string

pattern ^\d{4}-\d{2}-\d{2}$

QueryBoolean

boolean

SortDirection

string

One of: asc desc

TaxSummaryDto

Uuid

string (uuid)

VoidInvoiceInput