evenbooks
Sign inStart for free

Journal entries

The ledger itself, including manual entries and starting balances.

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 journal entries

get/journal

Drafts and posted entries with their lines, newest first by default (sort, dir). Filter by date range, status, an account the entry touches, source type or memo text. total counts every match; pass nextCursor as cursor for the next page.

Parameters

  • limitintegerquery

    1–200 · default 50

  • cursorstring · PageCursorquery
  • sortstringquery

    One of: date number

  • dirstring · SortDirectionquery

    One of: asc desc

  • fromstring · PlainDateStringquery
  • tostring · PlainDateStringquery
  • statusstring · JournalStatusquery

    One of: draft posted

  • accountIdstring · Uuidquery
  • sourceTypestring · JournalSourceTypequery
    21 possible values

    manual opening_balance invoice invoice_void credit_note credit_note_void payment payment_void allocation allocation_reversal refund refund_void purchase purchase_void transfer bank_categorization reversal adjustment processor_fee processor_payout import

  • qstringquery

    up to 200 characters

Response 200

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

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

Create a journal entry

post/journal
Write accessIdempotent

A manual entry; its lines must balance (400 unbalanced). Saved as a draft unless post: true, which posts it to the books at once (409 period_locked in a closed period). Posting refuses control accounts such as Accounts Receivable, which only invoices, payments and credit notes change. Idempotent with idempotencyKey.

Request body

CreateManualJournalInput

Response 200

JournalEntryDto (fields under Schemas)

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

Get a journal entry

get/journal/{id}

With its lines and totals.

Parameters

  • idstring (uuid)path · required

Response 200

JournalEntryDto (fields under Schemas)

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

Change a draft journal entry

patch/journal/{id}
Write access

Manual drafts only: posted entries are never edited (409 immutable); reverse them instead. Omitted fields stay as they are; lines, when sent, replace every line and must balance. Needs version from the last read (409 version_conflict otherwise).

Parameters

  • idstring (uuid)path · required

Request body

UpdateDraftJournalInput

Response 200

JournalEntryDto (fields under Schemas)

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

Delete a draft journal entry

delete/journal/{id}
Write access

Drafts only: posted entries cannot be deleted (409 immutable); reverse them instead. Returns no content.

Parameters

  • idstring (uuid)path · required

Response 204

Done; no body

No body.

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

Set the cash-basis amounts of an imported entry

patch/journal/{id}/cash-basis
Administrator keyWrite access

Administrators only. For a posted entry from a ledger import: components (active income and expense accounts, nonzero amounts) replace what the entry counts as on cash-basis reports; the accrual ledger is unchanged and its reversals follow. Refused when the entry or a reversal of it is in a closed period (409 period_locked). The reason is kept in History. Needs version from the last read (409 version_conflict otherwise).

Parameters

  • idstring (uuid)path · required

Request body

ReviewImportedCashInput

  • versionintegerrequired
  • reasonstringrequired

    1–500 characters

  • componentsarray of ImportCashComponentInputrequired

    up to 200 items

    Show 2 fields of each item

Response 200

JournalEntryDto (fields under Schemas)

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

Post a draft journal entry

post/journal/{id}/post
Write accessIdempotent

Posts the draft to the books and gives it an entry number. Refused in a closed period (409 period_locked), for an entry already posted (409 invalid_state) and for control accounts such as Accounts Receivable. Needs version from the last read (409 version_conflict otherwise). Idempotent with idempotencyKey.

Parameters

  • idstring (uuid)path · required

Request body

PostJournalInput

Response 200

JournalEntryDto (fields under Schemas)

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

Reverse a journal entry

post/journal/{id}/reverse
Write accessIdempotent

Posts a new entry dated date (not before the original, not in a closed period) with debits and credits swapped, links the two, and returns the reversal. An entry can be reversed once. Entries made by invoices, payments and credit notes are corrected from that record instead (400 validation). Completed reconciliations that cleared the entry become flagged. Idempotent with idempotencyKey.

Parameters

  • idstring (uuid)path · required

Request body

ReverseJournalInput

Response 200

JournalEntryDto (fields under Schemas)

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

Enter opening balances

post/journal/opening-balances
Administrator keyWrite accessIdempotent

Administrators only. Posts one entry dated date with each account’s starting balance in its natural direction (positive is a debit for assets and expenses); the difference goes to Opening Balance Equity and zero balances are skipped. Accounts Receivable and other control accounts are refused: enter open invoices instead. Idempotent with idempotencyKey.

Request body

OpeningBalancesInput

Response 200

JournalEntryDto (fields under Schemas)

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

Schemas

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

CashTreatment

string

One of: derived include exclude

DecimalString

decimal string

string

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

IdempotencyKey

string

8–128 characters

ImportCashComponentInput

ImportCashComponentInputOutput

JournalEntryDto

JournalLineDto

  • idstring
  • lineNointeger
  • accountIdstring
  • accountCodestringoptional
  • accountNamestringoptional
  • debitstring · DecimalString
  • creditstring · DecimalString
  • memostring or null
  • contactIdstring or null

JournalLineInput

JournalSourceType

string

21 possible values

manual opening_balance invoice invoice_void credit_note credit_note_void payment payment_void allocation allocation_reversal refund refund_void purchase purchase_void transfer bank_categorization reversal adjustment processor_fee processor_payout import

JournalStatus

string

One of: draft posted

NonNegativeDecimalString

string

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

OpeningBalanceLineInput

PageCursor

string

up to 2000 characters

PlainDateString

string

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

SortDirection

string

One of: asc desc

Uuid

string (uuid)