evenbooks
Sign inStart for free

Expenses

Money spent (purchases, bills paid, vendor refunds).

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 expenses

get/purchases

Money spent, and vendor refunds received. Newest first unless sort and dir say otherwise; accountId keeps expenses with a line in that category or paid from that account; q searches the memo and reference. List items omit attachments: get one expense for those.

Parameters

  • limitintegerquery

    1–200 · default 50

  • cursorstring · PageCursorquery
  • sortstringquery

    One of: date total vendor reference

  • dirstring · SortDirectionquery

    One of: asc desc

  • fromstring · PlainDateStringquery
  • tostring · PlainDateStringquery
  • contactIdstring · Uuidquery
  • accountIdstring · Uuidquery
  • statusstringquery

    One of: posted void

  • qstringquery

    up to 200 characters

Response 200

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

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

Record an expense

post/purchases
Write accessIdempotent

Records money already paid from paidFromAccountId (a bank account or card) and posts it to the books on date, split over the categories in lines; direction: inflow records a refund from a vendor. attachmentIds attaches uploaded receipts (see POST /attachments). Refused in a locked period (409 period_locked).

Request body

CreatePurchaseInput

  • datestring · PlainDateStringrequired
  • contactIdstring · Uuid or null
  • paidFromAccountIdstring · Uuidrequired
  • directionstring

    One of: outflow inflow

    default "outflow"

  • referencestring or null

    up to 100 characters

  • memostring or null

    up to 1000 characters

  • linesarray of PurchaseLineInputrequired

    1–100 items

    Show 3 fields of each item
    • accountIdstring · Uuidrequired
    • descriptionstring

      up to 500 characters · default ""

    • amountstring · PositiveDecimalStringrequired
  • attachmentIdsarray of string · Uuid

    up to 20 items · default []

  • bankTransactionIdstring · Uuid or null
  • idempotencyKeystring · IdempotencyKey

Response 200

PurchaseDto (fields under Schemas)

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

Get an expense

get/purchases/{id}

Includes its lines and attachments.

Parameters

  • idstring (uuid)path · required

Response 200

PurchaseDto (fields under Schemas)

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

Void an expense

post/purchases/{id}/void
Write accessIdempotent

Cancels an expense by posting a reversing entry on date (default: the expense date); a matched bank line goes back to unreviewed. Send version from your last read (409 version_conflict); refused in a locked period (409 period_locked).

Parameters

  • idstring (uuid)path · required

Request body

VoidPurchaseInput

Response 200

PurchaseDto (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.

DecimalString

decimal string

string

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

IdempotencyKey

string

8–128 characters

NonNegativeDecimalString

string

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

PageCursor

string

up to 2000 characters

PlainDateString

string

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

PositiveDecimalString

string

PurchaseDto

  • idstring
  • datestring · PlainDateString
  • contactIdstring or null
  • contactNamestring or nulloptional
  • directionstring

    One of: outflow inflow

  • paidFromAccountIdstring
  • paidFromAccountNamestringoptional
  • referencestring or null
  • memostring or null
  • totalstring · DecimalString
  • currencystring
  • statusstring

    One of: posted void

  • journalEntryIdstring
  • voidJournalEntryIdstring or null
  • bankTransactionIdstring or null
  • voidReasonstring or null
  • linesarray of PurchaseLineDto
  • attachmentsarray of objectoptional
    Show 4 fields of each item
    • idstring
    • fileNamestring
    • contentTypestring
    • sizeBytesnumber
  • versioninteger
  • createdAtstring

PurchaseLineDto

  • idstring
  • lineNointeger
  • accountIdstring
  • accountNamestringoptional
  • accountCodestringoptional
  • descriptionstring
  • amountstring · DecimalString

PurchaseLineInput

  • accountIdstring · Uuidrequired
  • descriptionstring

    up to 500 characters · default ""

  • amountstring · PositiveDecimalStringrequired

SortDirection

string

One of: asc desc

Uuid

string (uuid)