evenbooks
Sign inStart for free

Credit notes

Credits against 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.

List credit notes

get/credit-notes

Credit notes are credits you give a customer, used against their invoices or refunded. Newest issue date first unless sort and dir say otherwise. List items leave lines empty and omit allocations: get one credit note for those.

Parameters

  • limitintegerquery

    1–200 · default 50

  • cursorstring · PageCursorquery
  • sortstringquery

    One of: issueDate number total customer

  • dirstring · SortDirectionquery

    One of: asc desc

  • statusstring · DocumentStatusquery

    One of: draft issued paid void

  • contactIdstring · Uuidquery
  • fromstring · PlainDateStringquery
  • tostring · PlainDateStringquery
  • qstringquery

    up to 200 characters

Response 200

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

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

Create a draft credit note

post/credit-notes
Write access

A draft has no number and is not in the books yet; issue it with POST /credit-notes/{id}/issue. invoiceId links it to an issued invoice of the same customer (for reference; applying it is a separate step). The customer’s details are copied onto the credit note.

Request body

CreateCreditNoteInput

Response 200

CreditNoteDto (fields under Schemas)

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

Get a credit note

get/credit-notes/{id}

Includes its lines and its allocations (amounts applied to invoices).

Parameters

  • idstring (uuid)path · required

Response 200

CreditNoteDto (fields under Schemas)

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

Change a draft credit note

patch/credit-notes/{id}
Write access

Drafts only (409 immutable once issued). Send version from your last read (409 version_conflict if it changed). Omitted fields stay as they are; lines, when sent, replace all lines.

Parameters

  • idstring (uuid)path · required

Request body

UpdateCreditNoteInput

Response 200

CreditNoteDto (fields under Schemas)

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

Delete a draft credit note

delete/credit-notes/{id}
Write access

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

Parameters

  • idstring (uuid)path · required

Response 204

Done; no body

No body.

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

Apply a credit note to invoices

post/credit-notes/{id}/apply
Write accessIdempotent

Uses the credit to pay down invoices of the same customer: each allocation lowers that invoice’s balance and the credit note’s, and posts to the books on date (default: the credit note date). The total cannot exceed what is left on the credit note (400 over_allocation). Issued credit notes only; needs version from your last read; refused in a locked period (409 period_locked).

Parameters

  • idstring (uuid)path · required

Request body

ApplyCreditNoteInput

Response 200

CreditNoteDto (fields under Schemas)

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

Issue a credit note

post/credit-notes/{id}/issue
Write accessIdempotent

Gives the draft the next credit note number and posts it to the books on its issue date (income and sales tax reduced, the customer holds a credit). With applyToInvoiceId it is applied to that invoice at once, up to the invoice’s balance. Send version from your last read (409 version_conflict); the total must be above zero, and a locked period is refused (409 period_locked).

Parameters

  • idstring (uuid)path · required

Request body

IssueCreditNoteInput

  • versionintegerrequired
  • applyToInvoiceIdstring · Uuid or null
  • idempotencyKeystring · IdempotencyKey

Response 200

CreditNoteDto (fields under Schemas)

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

Void a credit note

post/credit-notes/{id}/void
Write accessIdempotent

Cancels an issued credit note by posting a reversing entry on date (default: its issue date). Refused once any of it is applied to invoices or refunded (409 invalid_state); void its refunds first. Needs version from your last read; refused in a locked period (409 period_locked). Delete a draft instead.

Parameters

  • idstring (uuid)path · required

Request body

VoidInvoiceInput (fields under Schemas)

Response 200

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

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

CreditNoteDto

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

IdempotencyKey

string

8–128 characters

LineTaxDto

NonNegativeDecimalString

string

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

PageCursor

string

up to 2000 characters

PaymentAllocationInput

PlainDateString

string

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

PositiveDecimalString

string

SortDirection

string

One of: asc desc

TaxSummaryDto

Uuid

string (uuid)

VoidInvoiceInput