Payments received
Money received from customers and how it is applied to invoices.
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.
Take a payment off an invoice
/allocations/{id}/reverseReverses one allocation (an amount of a payment applied to an invoice): the invoice owes that amount again and the money is unapplied on the payment. Posts to the books on date (default: the date it was applied); refused in a locked period (409 period_locked). Only payment allocations; credit note allocations are refused (400 validation). Returns the payment.
Parameters
idstring (uuid)path · required
Request body
ReverseAllocationInput
reasonstringrequireddatestring · PlainDateStringidempotencyKeystring · IdempotencyKey
Response 200
PaymentDto (fields under Schemas)
Errors 400 · 401 · 403 · 404 · 409 · 429
List payments received
/paymentsNewest first unless sort and dir say otherwise. unappliedOnly keeps payments with money not yet applied to invoices; q searches the reference and memo. Each payment includes its allocations (amounts applied to invoices).
Parameters
limitintegerquerycursorstring · PageCursorquerysortstringqueryOne of:
dateamountcustomerunapplieddirstring · SortDirectionqueryOne of:
ascdesccontactIdstring · Uuidqueryfromstring · PlainDateStringquerytostring · PlainDateStringquerystatusstringqueryOne of:
postedvoidunappliedOnlyboolean · QueryBooleanqueryqstringquery
Response 200
A page of PaymentDto ({ items, nextCursor, total }, see paging).
Errors 400 · 401 · 403 · 404 · 409 · 429
Record a payment received
/paymentsPosts money received into depositAccountId (a bank account or Undeposited Funds) and applies the allocations to the customer’s invoices; whatever is not applied stays on the payment as credit to apply later with POST /payments/{id}/allocate. Allocations cannot exceed the amount (400 over_allocation) and must all be invoices of one customer. bankTransactionId matches the payment to an unreviewed bank deposit of the same amount in that account. Refused in a locked period (409 period_locked).
Request body
CreatePaymentInput
contactIdstring · Uuid or nulldatestring · PlainDateStringrequiredamountstring · PositiveDecimalStringrequiredmethodstringOne of:
cashcheckcardachwireotherreferencestring or nullmemostring or nulldepositAccountIdstring · UuidrequiredisRefundableDepositbooleanallocationsarray of PaymentAllocationInputShow 2 fields of each item
invoiceIdstring · Uuidrequiredamountstring · PositiveDecimalStringrequired
bankTransactionIdstring · Uuid or nullidempotencyKeystring · IdempotencyKey
Response 200
PaymentDto (fields under Schemas)
Errors 400 · 401 · 403 · 404 · 409 · 429
Get a payment received
/payments/{id}Includes its allocations (amounts applied to invoices) and what is still unapplied or refunded.
Parameters
idstring (uuid)path · required
Response 200
PaymentDto (fields under Schemas)
Errors 400 · 401 · 403 · 404 · 409 · 429
Apply a payment to invoices
/payments/{id}/allocateApplies money left on a payment to invoices, lowering their balances, and posts that to the books on date (default: the payment date). The total cannot exceed the unapplied amount (400 over_allocation). Send version from your last read (409 version_conflict); refused on a void payment (409 invalid_state) or in a locked period (409 period_locked).
Parameters
idstring (uuid)path · required
Request body
AllocatePaymentInput
versionintegerrequireddatestring · PlainDateStringallocationsarray of PaymentAllocationInputrequiredShow 2 fields of each item
invoiceIdstring · Uuidrequiredamountstring · PositiveDecimalStringrequired
idempotencyKeystring · IdempotencyKey
Response 200
PaymentDto (fields under Schemas)
Errors 400 · 401 · 403 · 404 · 409 · 429
Void a payment received
/payments/{id}/voidCancels a payment by posting a reversing entry on date (default: the payment date); a matched bank line goes back to unreviewed. Refused while any of it is applied to invoices or refunded (409 invalid_state): reverse the allocations with POST /allocations/{id}/reverse and void the refunds first. Payments collected online cannot be voided; refund them instead. Needs version from your last read; refused in a locked period (409 period_locked).
Parameters
idstring (uuid)path · required
Request body
VoidPaymentInput
versionintegerrequiredreasonstringrequireddatestring · PlainDateStringidempotencyKeystring · IdempotencyKey
Response 200
PaymentDto (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.
AllocationDto
idstringsourceTypestringOne of:
paymentcredit_notepaymentIdstring or nullcreditNoteIdstring or nullinvoiceIdstringinvoiceNumberstring or nulloptionalamountstring · DecimalStringdatestring · PlainDateStringstatusstringOne of:
activereversedjournalEntryIdstring or nullreversalJournalEntryIdstring or nullsourceLabelstringoptional
DecimalString
decimal string
string
IdempotencyKey
string
NonNegativeDecimalString
string
PageCursor
string
PaymentAllocationInput
invoiceIdstring · Uuidrequiredamountstring · PositiveDecimalStringrequired
PaymentDto
idstringcontactIdstring or nullcontactNamestring or nulloptionaldatestring · PlainDateStringcurrencystringamountstring · DecimalStringmethodstringreferencestring or nullmemostring or nulldepositAccountIdstringdepositAccountNamestringoptionalisRefundableDepositbooleanstatusstringOne of:
postedvoidamountAllocatedstring · DecimalStringamountRefundedstring · DecimalStringunappliedAmountstring · DecimalStringjournalEntryIdstringvoidJournalEntryIdstring or nullvoidReasonstring or nullbankTransactionIdstring or nullprocessorChargeIdstring or nullallocationsarray of AllocationDtoversionintegercreatedAtstring
PlainDateString
string
PositiveDecimalString
string
QueryBoolean
boolean
SortDirection
string
One of: asc desc
Uuid
string (uuid)