🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add a basic account

Use to register a new bank, cash or credit-card account before importing transactions for it.

Not for chart-of-accounts entries. To add a posting account number, use postingaccounts_create.

Not idempotent: calling twice with the same name creates two accounts. Check accounts_list first. v1 offers no way to update or delete an account afterwards.

Endpoint: POST /accounts/add

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get all the accounts

Use to list the bank, cash and credit-card accounts that transactions can be booked against, e.g. to resolve an account name to the numeric account id the transaction tools expect.

Not the chart of accounts. For posting account numbers such as 1200 or 4400, use postingaccounts_list.

v1 offers no update or delete endpoint for accounts. An account created here can only be listed afterwards.

Endpoint: POST /accounts/get

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add comment to transaction or receipt

Add comment to transaction or receipt. NOTE: You have to submit either a transaction_id_by_customer or a receipt_id_by_customer.

Use to attach a free-text note to one receipt or one transaction, for example to record why a booking was categorised the way it was.

Exactly one of transaction_id_by_customer or receipt_id_by_customer must be set. v1 offers no endpoint to read, edit or delete comments, so a comment written here can only be seen in the BuchhaltungsButler web app.

Endpoint: POST /comments/add

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add cost location

Add a new cost location.

Use to create a cost centre before referencing it from a posting.

Not idempotent. Check cost_locations_list first to avoid a duplicate.

Endpoint: POST /cost-locations/add

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting.

delete cost location

Delete a cost location.

Use to remove a cost centre that is no longer needed.

Permanent. Unlike a deleted receipt there is no restore endpoint, so confirm with the user before calling.

Endpoint: POST /cost-locations/delete

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get cost locations

Get cost locations for a specified customer account. The response includes the number of returned rows and an array of cost locations data. NOTE: Each request is limited to 1000 cost locations!

Use to list the cost centres available for the cost_location fields on the posting tools.

Endpoint: POST /cost-locations/get

🟡 WRITE · updates data: Modifies existing master data in place.

update cost location

Update a cost location's name/description.

Use to rename an existing cost centre or change its number.

Overwrites the fields you send. Read the current record with cost_locations_list first if you intend a partial change.

Endpoint: POST /cost-locations/update

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create creditor

Create a creditor account.

Use to create one or more suppliers.

For customers you invoice, use debtors_create.

Takes one or many: pass an array of creditors in creditors. A single record is an array of one.

Not idempotent: check creditors_list first, since a repeated call creates duplicate suppliers. v1 offers no delete endpoint, so a creditor created here can only be updated afterwards, never removed.

Endpoint: POST /settings/add-batch/creditors

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get creditors

Get all creditors

Use to list suppliers, for example to resolve a supplier name to the creditor id the receipt and posting tools expect.

For customers you invoice, use debtors_list.

Supports limit and offset. Do not assume rows is the grand total. Continue paging until empty and check progress. v1 offers no delete endpoint for creditors, so they can only be created, listed and updated.

Endpoint: POST /settings/get/creditors

🟡 WRITE · updates data: Modifies existing master data in place.

update creditor

Update a creditor account.

Use to change a supplier's address, bank details or payment terms.

Overwrites the fields you send. Read the current record with creditors_list first if you intend a partial change.

Endpoint: POST /settings/update/creditor

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create debtor

Create a debtor account.

Use to create one or more customers.

For suppliers you buy from, use creditors_create.

Takes one or many: pass an array of debtors in debtors. A single record is an array of one.

Not idempotent: check debtors_list first. v1 offers no delete endpoint, so a debtor created here can only be updated afterwards, never removed.

Endpoint: POST /settings/add-batch/debtors

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get debitors

Get all debitors

Use to list customers, for example to resolve a customer name to the debtor id the receipt and posting tools expect.

For suppliers you buy from, use creditors_list.

Supports limit and offset. v1 offers no delete endpoint for debtors, so they can only be created, listed and updated.

Endpoint: POST /settings/get/debtors

🟡 WRITE · updates data: Modifies existing master data in place.

update debtor

Update a debtor account.

Use to change a customer's address, bank details or customer number.

Overwrites the fields you send. Read the current record with debtors_list first if you intend a partial change.

Endpoint: POST /settings/update/debtor

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create invoice

Add an invoice for the specified customer.

Use to issue a final outgoing invoice that is booked immediately.

For an invoice that should stay editable, use invoices_create_draft. For a structured XML invoice in XRechnung or ZUGFeRD format, use invoices_create_e_invoice.

Not idempotent: a second call issues a second invoice with a new number. v1 offers no endpoint to list, change or cancel an invoice once created.

Endpoint: POST /invoices/create

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create invoice draft

Add an invoice draft for the specified customer.

Use to prepare an invoice that a human should review and release in the BuchhaltungsButler web app.

A draft is not booked and carries no invoice number. To issue a final invoice directly, use invoices_create.

v1 offers no endpoint to list, edit or release drafts. Releasing happens in the web app.

Endpoint: POST /invoices/create/draft

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create e-invoice

Add an e-invoice for the specified customer.

Use when the recipient requires a structured electronic invoice, for example a German public-sector customer expecting XRechnung.

For an ordinary PDF invoice, use invoices_create.

Not idempotent. v1 offers no endpoint to list or cancel an e-invoice once created.

Endpoint: POST /invoices/create/e-invoice

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add postingaccount

Create a postingaccount.

Use to add an account number to the chart of accounts that the standard chart does not cover.

To register a bank or cash account, use accounts_create.

Not idempotent. v1 offers no delete endpoint, so a posting account created here can only be updated afterwards.

Endpoint: POST /settings/add/postingaccount

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get postingaccounts

Get all postingaccounts

Use to list the chart of accounts, for example to find the posting account number for office supplies before booking.

Not bank accounts. For the bank, cash and credit-card accounts transactions belong to, use accounts_list.

Supports limit and offset; a full SKR chart runs to several hundred rows. Do not assume rows is the grand total: continue paging until empty and check progress, or filter instead. v1 offers no delete endpoint for posting accounts.

Endpoint: POST /settings/get/postingaccounts

🟡 WRITE · updates data: Modifies existing master data in place.

update postingaccount

Update a postingaccount.

Use to rename a posting account or change its properties.

Overwrites the fields you send. Read the current record with postingaccounts_list first if you intend a partial change.

Endpoint: POST /settings/update/postingaccount

🟡 WRITE · links/unlinks records: Creates or removes an assignment between records (e.g. receipt ↔ transaction). Reversible.

assign receipt to free posting

Assign a receipt to a free posting.

Use to attach a receipt to a free posting that was booked without one, so the entry has its supporting document.

To link a receipt to a bank transaction rather than a posting, use transactions_assign_receipts.

Endpoint: POST /postings/assign/receipt-to-free-posting

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting.

cancel posting

Cancel a specified posting. Postings that are not fixed are deleted, fixed postings are cancelled by creating a reversal posting.

Use to take a booking out of the books entirely.

This is stronger than the postings_unconfirm_* tools: those keep the posting and only clear its confirmation, this one removes or reverses it. Prefer unconfirming when the goal is to edit and rebook.

The effect depends on the posting: one that is not yet fixed is deleted outright, a fixed one stays and is offset by a reversal posting, which leaves two visible entries in the journal. Confirm with the user before calling.

Endpoint: POST /postings/cancel

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add receipt posting

Add postings for a specified receipt. Important: Receipt postings are only available if creditor or debtor posting is activated!

IMPORTANT: If you add postings to a receipt with foreign currency, you have to get that receipt (/receipts/get/id_by_customer) and find the calculated amount before performing this request.

Use to book one or more receipts that already exist in BuchhaltungsButler, splitting each across posting accounts, VAT rates and cost centres.

For a journal entry with no receipt behind it, use postings_create_free.

Takes one or many: pass an array of receipts in receipts. A single record is an array of one.

The per-receipt arrays (postingaccounts, amounts, vats, postingtexts) are positional: index 0 of each describes the same split line, so they must all have the same length. Not idempotent. Reversible with postings_unconfirm_for_receipt while the posting is not fixed.

Endpoint: POST /postings/add-batch/receipts

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add transaction posting

Add postings for a specified transaction.

Use to book one or more bank transactions, splitting each across posting accounts, VAT rates and cost centres.

For a journal entry with no bank transaction behind it, use postings_create_free.

Takes one or many: pass an array of transactions in transactions. A single record is an array of one.

The per-transaction arrays are positional and must all have the same length. Not idempotent. Reversible with postings_unconfirm_for_transaction while the posting is not fixed.

Endpoint: POST /postings/add-batch/transactions

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add free posting

Add a free posting.

Use to book a debit/credit pair that is not tied to an existing receipt or bank transaction, such as a manual accrual or a correction.

If the booking documents a receipt, use postings_create_for_receipt. If it settles a bank transaction, use postings_create_for_transaction.

Takes one or many: pass an array of free postings in free_postings. A single record is an array of one.

A "free" posting is BuchhaltungsButler's term for a standalone journal entry: you name both sides yourself via postingaccount_debit and postingaccount_credit. Not idempotent, so a repeated call books the amount twice. A receipt can be attached afterwards with postings_assign_receipt_to_free.

Endpoint: POST /postings/add-batch/free

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get postings

Get postings for a specified customer account. The response includes the number of returned rows and an array of postings data. NOTE: Each request is limited to 1000 postings!

Use to read the booking journal, filtered by date range or posting account.

Supports limit and offset. Ask for a bounded date range rather than paging through a whole financial year.

Endpoint: POST /postings/get

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible.

unconfirm receipt posting

Remove postings for a specified receipt by unconfirming them. This will only work if the postings are not fixed.

Use to send a receipt posting back to the unconfirmed state so it can be corrected.

This keeps the posting and only clears its confirmation. To remove the posting itself, use postings_cancel.

Only works while the posting is not fixed.

Endpoint: POST /postings/unconfirm/receipt

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible.

unconfirm transaction posting

Remove postings for a specified transaction by unconfirming them. This will only work if the postings are not fixed.

Use to send a transaction posting back to the unconfirmed state so it can be corrected.

This keeps the posting and only clears its confirmation. To remove the posting itself, use postings_cancel.

Only works while the posting is not fixed.

Endpoint: POST /postings/unconfirm/transaction

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible.

unconfirm free posting

Remove a specified free posting by unconfirming it. This will only work if the posting is not fixed.

Use to send a free posting back to the unconfirmed state so it can be corrected.

This keeps the posting and only clears its confirmation. To remove the posting itself, use postings_cancel.

Only works while the posting is not fixed. Fixed postings can no longer be unconfirmed.

Endpoint: POST /postings/unconfirm/free

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add a receipt

Add a receipt into the specified customer account. NOTE: Use this endpoint, to add a receipt without a file!

Use to record receipts that have no file attached, for example when the document lives in another system.

If you have the actual PDF or image, use receipts_upload instead so BuchhaltungsButler can read the document and pre-fill its data.

Takes one or many: pass an array of receipts in receipts. A single record is an array of one.

Not idempotent: a repeated call creates duplicate receipts. The response reports per-item success, so a partial failure leaves the successful entries in place.

Endpoint: POST /receipts/addBatch

🔴 DESTRUCTIVE · deletes data: Deletes or cancels a record. Confirm with the user before calling. Receipt deletes are restorable; cost-location deletes are not. Cancelling a posting deletes it if it is not yet fixed, otherwise it books a reversal posting.

delete receipt by id_by_customer

Mark a receipt as deleted for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first.

Use to remove a receipt that was filed by mistake.

Recoverable: receipts_restore brings the receipt back. Confirm with the user before calling.

Endpoint: POST /receipts/delete/id_by_customer

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get receipt by id_by_customer

Get a single receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first. The response includes an array of receipt data.

Use to fetch a single receipt whose id you already have.

To search or page through receipts, use receipts_list.

id_by_customer is the per-customer counter shown in the BuchhaltungsButler UI, not a global database id.

Endpoint: POST /receipts/get/id_by_customer

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get receipts

Get receipts for a specified customer account. The response includes the number of returned rows and an array of receipts data.

Use to search receipts by direction, date range or payment status.

To fetch one known receipt, use receipts_get_by_id.

list_direction is required and selects inbound or outbound receipts. Supports limit and offset; observed rows counts only the returned page. Continue paging until empty, deduplicate IDs and check progress.

Endpoint: POST /receipts/get

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get all transactions assigned to a specific receipt

Get all transactions assigned to a specific receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first.

Use to see which bank transactions are linked to a given receipt, for example to check whether an invoice has been matched to a payment.

For the opposite direction, use transactions_list_assigned_receipts.

Endpoint: POST /receipts/assigned-transactions/get

🟡 WRITE · reverts state: Reverts a prior state change (un-confirm a posting, restore a deleted receipt). Reversible.

restore deleted receipt by id_by_customer

Restore a marked as deleted receipt for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/receipts/get method" first.

Use to bring back a receipt that was deleted with receipts_delete.

Endpoint: POST /receipts/restore/id_by_customer

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

upload receipt

Upload a receipt into the specified customer account. The receipt will be processed by the BuchhaltungsButler technology. The response includes the filename (without extension) of the receipt as it is stored.

Note: max 10 requests per minute

Use to send the actual receipt file. BuchhaltungsButler runs document recognition on it and returns the stored filename.

To record a receipt without a file, use receipts_create.

Rate limited to 10 requests per minute. Not idempotent, so uploading the same file twice creates two receipts.

Endpoint: POST /receipts/upload

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create bwa report

Triggers the creation of a BWA report ("Betriebswirtschaftliche Auswertung").

The report is generated asynchronously in the background. The response contains the id_by_customer of the created report, which may be used to retrieve it once the generation has been finished.

A new report may only be requested once the generation of a previously requested report of the same type has been finished.

Use to request a BWA (Betriebswirtschaftliche Auswertung, the German management report). Step one of two.

This only triggers generation. To read the finished report, call reports_get_bwa afterwards.

Runs asynchronously and returns an id, not the report. A new BWA can only be requested once the previous one has finished, and it replaces the previous one.

Endpoint: POST /reports/create/bwa

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

create sums report

Triggers the creation of a sums report ("Summen- und Saldenliste"). The report is always created for all of the customer's postingaccounts.

The report is generated asynchronously in the background. The response contains the id_by_customer of the created report, which may be used to retrieve it once the generation has been finished.

A new report may only be requested once the generation of a previously requested report of the same type has been finished.

Use to request a sums and balances report (Summen- und Saldenliste). Step one of two.

To read the finished report, call reports_get_sums afterwards.

Runs asynchronously and returns an id. A new report may only be requested once the previous one has finished, and it replaces the previous one.

Endpoint: POST /reports/create/sums

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get bwa report

Returns a previously created BWA report ("Betriebswirtschaftliche Auswertung").

Reports are generated asynchronously, so a report is only available once its generation has been finished. Note that creating a new report of the same type replaces the previously created one.

Use to read a BWA that reports_create_bwa has finished generating. Step two of two.

Returns nothing useful until generation has finished. If the report is not ready, wait and retry rather than requesting a new one, since a new request replaces the pending one.

Endpoint: POST /reports/get/bwa

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get sums report

Returns a previously created sums report ("Summen- und Saldenliste").

Reports are generated asynchronously, so a report is only available once its generation has been finished. Note that creating a new report of the same type replaces the previously created one.

Use to read a sums and balances report that reports_create_sums has finished generating. Step two of two.

For the individual bookings behind one posting account, use reports_get_sums_ledger.

Endpoint: POST /reports/get/sums

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get sums report postingaccount ledger

Returns the postingaccount ledger ("Kontenblatt") of one postingaccount, holding its postings of the requested period.

The postingaccount numbers available for a sums report are provided by reports/get/sums, both as the keys of the 'sums' object and as its entries' 'postingaccount_number'.

In contrast to the report itself the ledger is created on the fly, so no report has to be created beforehand. Note that retrieving the ledger of a postingaccount holding a lot of postings may take a while.

Use to read one posting account's ledger for a bounded date range.

For the totals across all posting accounts, use reports_get_sums.

The API returns the ledger on demand; no previously generated sums report or report ID is required.

Endpoint: POST /reports/get/sums/ledger

🟡 WRITE · links/unlinks records: Creates or removes an assignment between records (e.g. receipt ↔ transaction). Reversible.

assign receipt to transaction

Assign a receipt to a transaction.

Use to match receipts to the bank transactions that paid them, one pair or many at once.

To attach a receipt to a posting rather than a bank transaction, use postings_assign_receipt_to_free.

Takes one or many: pass an array of transactions to receipts in transactions_to_receipts. A single record is an array of one.

Reversible with transactions_unassign_receipt. Creating the link does not book anything: use postings_create_for_transaction to post the transaction.

Endpoint: POST /transactions/assign-batch/receipt

🟡 WRITE · creates data: Creates new records (receipts, transactions, postings, invoices, master data). Not idempotent: calling twice may create duplicates.

add transaction

Add a transaction to a payment account of the specified customer.

Use to import bank transactions that no bank connection delivers automatically, for example from a CSV export or a cash book.

Takes one or many: pass an array of transactions in transactions. A single record is an array of one.

Not idempotent and there is no duplicate detection: re-importing the same statement books every line a second time. Check transactions_list for the date range first. v1 offers no endpoint to update or delete an imported transaction.

Endpoint: POST /transactions/addBatch

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get transaction by id_by_customer

Get a single transaction for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/transactions/get method" first. The response includes an array of transaction data.

Use to fetch a single bank transaction whose id you already have.

To search or page through transactions, use transactions_list.

id_by_customer is the per-customer counter shown in the BuchhaltungsButler UI, not a global database id.

Endpoint: POST /transactions/get/id_by_customer

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get transactions

Get transactions for a specified customer account. The response includes the number of returned rows and an array of transaction datas.

Use to search bank transactions by account and date range.

To fetch one known transaction, use transactions_get_by_id.

For multi-page exports, prefer id_by_customer_from with limit and fixed account/date filters: it is exclusive and forces ID-ascending order. Start at 0, then use the greatest returned ID without incrementing it; omit offset. Validate IDs and forward progress and continue until empty. Offset pages have overlapped in observed filtered exports; deduplication and an empty final page do not prove completeness. Reconcile IDs/counts and signed amounts independently. rows counts the returned page, not the grand total; concurrent changes still need a separate check.

Endpoint: POST /transactions/get

🟢 READ-ONLY: Fetches data. Makes no changes to the accounting records.

get all receipts assigned to a specific transaction

Get all receipts assigned to a specific transaction for a specified customer account by id_by_customer. You can get the "id_by_customer" by using the "/transactions/get method" first.

Use to see which receipts are linked to a given bank transaction, for example to check whether a payment has its invoice attached.

For the opposite direction, use receipts_list_assigned_transactions.

Endpoint: POST /transactions/assigned-receipts/get

🟡 WRITE · links/unlinks records: Creates or removes an assignment between records (e.g. receipt ↔ transaction). Reversible.

unassign a specific receipt from a transaction

Unassign a specific receipt from a transaction.

Use to undo a receipt-to-transaction match that was made in error.

Removes only the link. Neither the receipt nor the transaction is deleted.

Endpoint: POST /transactions/unassign/receipt