API reference

Bills

What vendors billed: drafts entered freely, one vendor's number taken once, approved onto payables with their due day, voided by reversal.

GET/v1/billsList bills
POST/v1/billsEnter a draft bill
GET/v1/bills/{bill_id}Get a bill
PATCH/v1/bills/{bill_id}Change a draft bill
DELETE/v1/bills/{bill_id}Delete a draft bill
POST/v1/bills/{bill_id}/approveApprove a bill onto the books
GET/v1/bills/{bill_id}/comparisonCompare a bill with its vendor's usual and last bill
POST/v1/bills/{bill_id}/send_backSend a bill LedgerIt approved back to draft
POST/v1/bills/{bill_id}/voidVoid an approved bill

Guides: Enter and approve vendor bills

List bills

GET/v1/bills

client.bills.list()

The bills of these books, the newest first, each with what is still owed on it.

Parameters

Name	Type	Description
`status`Query	string or null	Only `draft`, `approved` or `void` bills.
`party_id`Query	string or null	An id that starts with `party_`.
`limit`Query	integer	Page size, 1–200. Default 50
`cursor`Query	string or null	The `next_cursor` of the previous page.

Response

200BillPage

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/bills" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Enter a draft bill

POST/v1/bills· Idempotent

client.bills.create()

Write a draft of a vendor's bill. Nothing is on the books until it is approved. The vendor's number is taken once per vendor: the same number again is refused with conflict, since it is the same bill entered twice. It falls due on the vendor's terms (30 days without) when no due day is given.

Request body

BillCreate

Response

201BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/bills" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"bill_date":"2026-09-30","lines":[{"account_id":"…","amount":0,"description":"…"}],"party_id":"…","vendor_number":"…"}'

Get a bill

GET/v1/bills/{bill_id}

client.bills.get()

One bill, its lines and what is still owed on it.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Response

200BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/bills/{bill_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Change a draft bill

PATCH/v1/bills/{bill_id}· Idempotent

client.bills.update()

Change a draft: any field given, and every line at once when lines is. An approved bill is refused with conflict: void it and enter another.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Request body

BillUpdate

Response

200BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X PATCH "https://api.ledgerit.ai/v1/bills/{bill_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Delete a draft bill

DELETE/v1/bills/{bill_id}· Idempotent

client.bills.delete()

Delete a draft. An approved bill is refused with conflict: it is voided instead, and stays.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Response

204No content

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X DELETE "https://api.ledgerit.ai/v1/bills/{bill_id}" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Approve a bill onto the books

POST/v1/bills/{bill_id}/approve· Idempotent

client.bills.approve()

Put a draft on the books: one entry on the bill's day, each line on its account against the total on accounts payable naming the vendor. What is owed then ages from the bill's due day.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Response

200BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/bills/{bill_id}/approve" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Compare a bill with its vendor's usual and last bill

GET/v1/bills/{bill_id}/comparison

client.bills.compare()

A bill beside what its vendor usually bills and beside its last bill, account by account, so a price rise is questioned before the bill is approved or paid. The usual is the higher of the vendor's bills before this one in the rhythm it kept when the bill came in; above_usual is set when the bill comes to at least 1.25 times it, the same rule as the upcoming bills report.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Response

200BillComparisonOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl "https://api.ledgerit.ai/v1/bills/{bill_id}/comparison" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN"

Send a bill LedgerIt approved back to draft

POST/v1/bills/{bill_id}/send_back· Idempotent

client.bills.sendBack()

Undo LedgerIt's approval of a bill: its entry is reversed and it is a draft again, its number, lines and document as they were, to check, change and approve. Only a bill LedgerIt approved (approved_by_ledgerit); any other is refused with conflict, as is one with a payment applied.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Response

200BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/bills/{bill_id}/send_back" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"

Void an approved bill

POST/v1/bills/{bill_id}/void· Idempotent

client.bills.void()

Take an approved bill off the books by reversing its entry. Refused with conflict while a payment is applied to it.

Parameters

Name	Type	Description
`bill_id`Path · Required	string	An id that starts with `bill_`.

Request body

BillVoid

Response

200BillOut

Errors

400: The request was malformed or a parameter is invalid.
401: No valid credential was sent.
403: The credential or the member's role does not allow this.
404: No such resource in this ledger.
409: A conflicting request, e.g. one with the same Idempotency-Key still running.
422: A well-formed request a business rule refused.
429: Too many requests; retry after the Retry-After header.
500: Something failed on our side; the request_id identifies it.

Example

curl

curl -X POST "https://api.ledgerit.ai/v1/bills/{bill_id}/void" \
  -H "Authorization: Bearer $LEDGERIT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'

Objects

The objects these operations take and return.

BillPage

Name	Type	Description
`data`Required	array of BillOut
`has_more`Required	boolean
`next_cursor`Required	string or null

BillCreate

Name	Type	Description
`bill_date`Required	string (date)
`document_id`	string or null	An id that starts with `doc_`.
`due_date`	string (date) or null	When it falls due; the vendor's payment terms from the bill's day (30 days without) when left out.
`lines`Required	array of BillLineIn
`memo`	string or null
`party_id`Required	string	The vendor: a counterparty of these books.
`vendor_number`Required	string	The vendor's own number for the bill; once per vendor in these books.

BillOut

Name	Type	Description
`amount_due`Required	string	What is still owed to the vendor on it today; 0 for a draft or a void bill.
`approved_at`Required	string (date-time) or null
`approved_by_ledgerit`Required	boolean	LedgerIt approved it, not a person: a usual bill that came to the bills address, from a vendor billing on a rhythm, within 5% of its usual, on the account of its last bill. While it is still fully owed, `send_back` returns it to a draft.
`bill_date`Required	string (date)
`created_at`Required	string (date-time)
`currency`Required	string
`document_id`Required	string or null	An id that starts with `doc_`.
`due_date`Required	string (date)
`entry_id`Required	string or null	An id that starts with `je_`.
`id`Required	string	An id that starts with `bill_`.
`lines`Required	array of BillLineOut
`memo`Required	string or null
`party_id`Required	string	An id that starts with `party_`.
`row_version`Required	integer
`status`Required	string	`draft`, `approved` or `void`.
`total`Required	string
`vendor_number`Required	string
`void_entry_id`Required	string or null	An id that starts with `je_`.
`voided_at`Required	string (date-time) or null

BillUpdate

Name	Type	Description
`bill_date`	string (date) or null
`document_id`	string or null	An id that starts with `doc_`.
`due_date`	string (date) or null
`lines`	array of BillLineIn or null	Replaces every line when given.
`memo`	string or null
`party_id`	string or null	An id that starts with `party_`.
`vendor_number`	string or null

BillComparisonOut

Name	Type	Description
`above_usual`Required	string or null	How much the bill comes to over the vendor's usual bill, when it is at least 1.25× it: worth a look before it is approved or paid.
`accounts`Required	array of AccountChangeOut	Each account either bill charges, this bill's first in its line order; empty without a last bill.
`bill_id`Required	string	An id that starts with `bill_`.
`currency`Required	string
`every_months`Required	integer or null	Months between the vendor's bills, when it kept a rhythm as of the bill: 1, 3, 12.
`previous_bill`Required	PreviousBillOut or null	The vendor's bill before this one, in the same currency and not voided.
`total`Required	string
`usual_amount`Required	string or null	What the bill is measured against, when the vendor kept a rhythm as of the bill: the higher of its bills before this one in that rhythm (the two before it monthly or quarterly, last year's yearly).

BillVoid

Name	Type	Description
`reason`	string or null	Why it is voided; written on the reversal.

BillLineIn

Name	Type	Description
`account_id`Required	string	The expense or asset account it is spent from.
`amount`Required	number \| string	What it cost; negative for a credit on the bill.
`description`Required	string	What the vendor charged for.
`service_end`	string (date) or null	The last day of the service it charges, if any.
`service_start`	string (date) or null	The first day of the service it charges, if any.

BillLineOut

Name	Type	Description
`account_id`Required	string	An id that starts with `gla_`.
`amount`Required	string
`description`Required	string
`line_no`Required	integer
`service_end`Required	string (date) or null
`service_start`Required	string (date) or null

AccountChangeOut

Name	Type	Description
`account_id`Required	string	An id that starts with `gla_`.
`amount`Required	string	What this bill charges the account; 0 when it does not.
`change`Required	string	`amount` less `previous_amount`.
`previous_amount`Required	string	What the last bill charged the account; 0 when it did not.

PreviousBillOut

Name	Type	Description
`bill_date`Required	string (date)
`id`Required	string	An id that starts with `bill_`.
`total`Required	string
`vendor_number`Required	string	The vendor's own number for it.