Evenbead docs
Contents

Sales purchases

26 operations. All areas

POST/v1/contacts

Add a customer or vendor

  • Operation createContact
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • kind "customer" | "vendor", required
  • name string, required
  • email string
  • terms_days integer
  • is_1099 boolean Vendors only: this vendor gets a 1099
  • tax_id string The vendor's SSN or EIN (9 digits; dashes allowed). Write-only: Evenbead keeps only the last four digits and never returns the number.
Responses
  • 201 Created (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/contacts

Customers and vendors with open and overdue balances

  • Operation listContacts
  • Scope: read
  • Read
Parameters
  • kind query, "customer" | "vendor"
  • include_inactive query, boolean
  • as_of query, string
Responses
  • 200 Contacts (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/contacts/{id}

A customer or vendor with their documents and payments

  • Operation getContact
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • as_of query, string
Responses
  • 200 Contact (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/contacts/{id}/update

Rename, change email or terms, or (de)activate a customer or vendor; for vendors, the 1099 flag and the tax ID (only its last four digits are kept)

  • Operation updateContact
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • name string
  • email string | null
  • terms_days integer
  • active boolean
  • is_1099 boolean Vendors only: this vendor gets a 1099
  • tax_id string | null The vendor's SSN or EIN (9 digits; dashes allowed). Write-only: Evenbead keeps only the last four digits and never returns the number. null forgets it.
Responses
  • 200 Updated (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/items

Add a product or service with default accounts and prices

  • Operation createItem
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • name string, required
  • kind "service" | "non_inventory", required
  • description string
  • sales_price_cents integer Integer cents (100 = $1.00). Never a float.
  • purchase_cost_cents integer Integer cents (100 = $1.00). Never a float.
  • income_account string
  • expense_account string
  • taxable boolean Lines with this item are taxable by default
Responses
  • 201 Created (object)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/items

Products and services

  • Operation listItems
  • Scope: read
  • Read
Parameters
  • include_inactive query, boolean
Responses
  • 200 Items (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

POST/v1/invoices

Create and post an invoice (Dr AR, Cr income per line). Agents: auto-posts within policy, otherwise queues for approval. dry_run previews.

  • Operation createInvoice
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required The customer
  • number string Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted
  • doc_date string, required Calendar date, YYYY-MM-DD.
  • due_date string Calendar date, YYYY-MM-DD.
  • terms_days integer
  • reference string Vendor invoice no., PO no.
  • memo string
  • control_account string AR/AP control account (default: the first active one)
  • tax_rate_id string Sales-tax rate for the taxable lines (adds a tax line on the rate's payable account)
  • lines array of DocumentLineInput, required
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run: the document, its number, the exact entry, policy verdict; nothing written (DocumentResult)
  • 201 Posted (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/credit-memos

Create and post a credit memo for a customer (Dr income, Cr AR); apply it to invoices with /v1/documents/{id}/apply

  • Operation createCreditMemo
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required The customer
  • number string Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted
  • doc_date string, required Calendar date, YYYY-MM-DD.
  • due_date string Calendar date, YYYY-MM-DD.
  • terms_days integer
  • reference string Vendor invoice no., PO no.
  • memo string
  • control_account string AR/AP control account (default: the first active one)
  • tax_rate_id string Sales-tax rate for the taxable lines (adds a tax line on the rate's payable account)
  • lines array of DocumentLineInput, required
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run: the document, its number, the exact entry, policy verdict; nothing written (DocumentResult)
  • 201 Posted (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/bills

Record and post a vendor bill (Dr expense per line, Cr AP). Same governance as invoices; dry_run previews.

  • Operation createBill
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required The vendor
  • number string Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted
  • doc_date string, required Calendar date, YYYY-MM-DD.
  • due_date string Calendar date, YYYY-MM-DD.
  • terms_days integer
  • reference string Vendor invoice no., PO no.
  • memo string
  • control_account string AR/AP control account (default: the first active one)
  • lines array of DocumentLineInput, required
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run: the document, its number, the exact entry, policy verdict; nothing written (DocumentResult)
  • 201 Posted (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/vendor-credits

Record a vendor credit (Dr AP, Cr expense); apply it to bills with /v1/documents/{id}/apply

  • Operation createVendorCredit
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required The vendor
  • number string Optional; assigned (INV-0001, CM-, BILL-, VC-) when omitted
  • doc_date string, required Calendar date, YYYY-MM-DD.
  • due_date string Calendar date, YYYY-MM-DD.
  • terms_days integer
  • reference string Vendor invoice no., PO no.
  • memo string
  • control_account string AR/AP control account (default: the first active one)
  • lines array of DocumentLineInput, required
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run: the document, its number, the exact entry, policy verdict; nothing written (DocumentResult)
  • 201 Posted (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/documents

Invoices, credit memos, bills, vendor credits, sales receipts, refunds, expenses, checks and transfers with open balance and status

  • Operation listDocuments
  • Scope: read
  • Read
Parameters
  • kind query, "invoice" | "credit_memo" | "bill" | "vendor_credit" | "sales_receipt" | "refund" | "vendor_refund" | "expense" | "check" | "transfer"
  • side query, "sales" | "purchases" | "spending"
  • status query, "open" | "partial" | "paid" | "applied" | "void" | "overdue" | "unpaid"
  • contact_id query, string
  • from query, string
  • to query, string
  • as_of query, string
  • limit query, integer
Responses
  • 200 Documents, newest first (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/documents/{id}

One document with its lines and the payments and credits applied to (or from) it

  • Operation getDocument
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Document (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/documents/{id}/void

Void a document by posting the exact reversal of its entry. Invoices/bills need any payments or credits voided first.

  • Operation voidDocument
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
  • void_date string Calendar date, YYYY-MM-DD.
  • soft_lock_override_reason string
  • dry_run boolean
Responses
  • 200 Voided (or the dry-run preview) (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/documents/{id}/apply

Apply a credit memo or vendor credit to open invoices or bills of the same customer or vendor

  • Operation applyCredit
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • applications array of object, required
  • applied_on string Calendar date, YYYY-MM-DD.
  • dry_run boolean
Responses
  • 200 Applied (or the dry-run preview) (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/payments/received

Record a customer payment applied to invoices (Dr bank, Cr AR), optionally from an unmatched bank deposit line (bank_line_id), which it categorizes. Same governance as propose.

  • Operation receivePayment
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required
  • payment_date string Defaults to the bank line's date
  • account string Bank, cash, undeposited-funds or card account (defaults to the bank line's account)
  • amount_cents integer The whole payment (default: the applications). Anything above the applications stays unapplied: credit on account (deposit, overpayment), applied later or refunded.
  • applications array of object
  • control_account string AR/AP control account for a payment with no applications (default: the first active one)
  • bank_line_id string An unmatched bank line this payment is (same amount; deposit for received, withdrawal/charge for made)
  • number string
  • reference string Check no., remittance id
  • memo string
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run (DocumentResult)
  • 201 Recorded (and the bank line categorized) (DocumentResult)
  • 202 Queued for approval (the bank line is 'proposed' until decided) (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/payments/made

Pay vendor bills (Dr AP, Cr bank or card), optionally from an unmatched bank or card line (bank_line_id). Same governance as propose.

  • Operation payBills
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required
  • payment_date string Defaults to the bank line's date
  • account string Bank, cash, undeposited-funds or card account (defaults to the bank line's account)
  • amount_cents integer The whole payment (default: the applications). Anything above the applications stays unapplied: credit on account (deposit, overpayment), applied later or refunded.
  • applications array of object
  • control_account string AR/AP control account for a payment with no applications (default: the first active one)
  • bank_line_id string An unmatched bank line this payment is (same amount; deposit for received, withdrawal/charge for made)
  • number string
  • reference string Check no., remittance id
  • memo string
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run (DocumentResult)
  • 201 Recorded (and the bank line categorized) (DocumentResult)
  • 202 Queued for approval (the bank line is 'proposed' until decided) (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/payments

Payments received and made, newest first (unapplied=true: only those with credit on account)

  • Operation listPayments
  • Scope: read
  • Read
Parameters
  • kind query, "received" | "made"
  • contact_id query, string
  • limit query, integer
  • unapplied query, boolean
Responses
  • 200 Payments (object)
  • Errors 400, 401, 403, 429, 500 (Error: error.type, message)

GET/v1/payments/{id}

One payment with its applications

  • Operation getPayment
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Payment (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/payments/{id}/void

Void a payment: posts the exact reversal, releases its applications (documents reopen) and its bank line

  • Operation voidPayment
  • Scope: approve
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • reason string, required
  • void_date string Calendar date, YYYY-MM-DD.
  • soft_lock_override_reason string
  • dry_run boolean
Responses
  • 200 Voided (or the dry-run preview) (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/sales-receipts

Record a sale paid on the spot (Dr the deposit account, Cr income per line, plus sales tax). Never open, not in AR. Same governance as invoices; dry_run previews.

  • Operation createSalesReceipt
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • contact_id string, required The customer
  • number string Optional; assigned (SR-0001) when omitted
  • doc_date string, required Calendar date, YYYY-MM-DD.
  • deposit_account string, required Bank, cash or undeposited-funds account the money went to
  • reference string
  • memo string
  • tax_rate_id string
  • lines array of DocumentLineInput, required
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run (DocumentResult)
  • 201 Posted (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/payments/{id}/apply

Apply a payment's unapplied amount (credit on account, deposit, prepayment) to open invoices or bills of the same customer or vendor

  • Operation applyPayment
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • applications array of object, required
  • applied_on string Calendar date, YYYY-MM-DD.
  • dry_run boolean
Responses
  • 200 Applied (or the dry-run preview) (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)

POST/v1/refunds

Refund a customer from the unapplied part of a payment (deposit, overpayment) or a credit memo: a refund document (Dr AR, Cr bank) paid at once by its source. Same governance as invoices; dry_run previews.

  • Operation createRefund
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • payment_id string Refund from this payment received (give this or credit_id)
  • credit_id string Refund from this credit memo
  • refund_date string, required Calendar date, YYYY-MM-DD.
  • account string, required Bank, cash or card account the money leaves
  • amount_cents integer Default: everything left on the source
  • number string Optional; assigned (RF-0001) when omitted
  • reference string Check no.
  • memo string
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run (DocumentResult)
  • 201 Refunded (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/documents/{id}/pdf

Render an invoice, credit memo or sales receipt as a PDF (server-side, Plus Jakarta Sans embedded; nothing is sent anywhere)

  • Operation renderDocumentPdf
  • Scope: read
  • Read
Parameters
  • id path, string, required
  • format query, "pdf" | "base64"
Responses
  • 200 The PDF (or with format=base64, JSON) (PdfFile)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/vendor-refunds

Record money a vendor paid back, from the unapplied part of a payment made (a prepayment, an overpaid bill) or a vendor credit: a vendor refund document (Cr AP, Dr the bank account) paid at once by its source. Same governance as bills; dry_run previews.

  • Operation createVendorRefund
  • Scope: propose
  • Write: needs Idempotency-Key (or dry_run)
Request body
  • payment_id string Refund of this payment made (give this or credit_id)
  • credit_id string Refund of this vendor credit
  • refund_date string, required Calendar date, YYYY-MM-DD.
  • account string, required Bank, cash or card account the money arrives in
  • amount_cents integer Default: everything left on the source
  • number string Optional; assigned (VRF-0001) when omitted
  • reference string Deposit or check no.
  • memo string
  • dry_run boolean
  • confidence number
  • soft_lock_override_reason string
Responses
  • 200 Dry run (DocumentResult)
  • 201 Refunded (DocumentResult)
  • 202 Queued for approval (DocumentResult)
  • Errors 400, 401, 403, 409, 422, 429, 500 (Error: error.type, message)

GET/v1/items/{id}

One product or service

  • Operation getItem
  • Scope: read
  • Read
Parameters
  • id path, string, required
Responses
  • 200 Item (object)
  • Errors 400, 401, 403, 404, 429, 500 (Error: error.type, message)

POST/v1/items/{id}/update

Edit a product or service (name, kind, description, sales price, income account, purchase cost and account, taxable) or deactivate/reactivate it. Documents keep what they posted. Audited; dry_run previews.

  • Operation updateItem
  • Scope: admin
  • Write: needs Idempotency-Key (or dry_run)
Parameters
  • id path, string, required
Request body
  • name string
  • kind "service" | "non_inventory"
  • description string
  • sales_price_cents integer | null Integer cents (100 = $1.00). Never a float.
  • purchase_cost_cents integer | null Integer cents (100 = $1.00). Never a float.
  • income_account string | null An income account (selling); null removes it
  • expense_account string | null An expense or inventory-asset account (buying); null removes it
  • taxable boolean
  • active boolean
  • dry_run boolean
Responses
  • 200 Updated (or, with dry_run, what it would be) (object)
  • Errors 400, 401, 403, 404, 409, 422, 429, 500 (Error: error.type, message)