# Billomat MCP Server — 145 tools via DADL

The Billomat DADL turns Billomat's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 145 tools — invoice, offer, credit, confirmation, delivery, recurring, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.

Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Billomat feature area.

**Source:** [Billomat REST API](https://www.billomat.com/en/api/)

**Updated:** 2026-07-20

**Tags:** cloud, e-commerce, crud, user-management, file-management, notifications, logging, automation, auth:apikey

## Which Billomat endpoints are covered?

**58%** (145 of ~250 endpoints).

**Focus:** Billomat invoicing: invoices (items, payments, comments, tags), offers (estimates, quotes), credit notes, recurring invoices, clients (contacts), articles, taxes, units, suppliers, incoming invoices.

**Missing:** article property values, client/supplier property values, inbox documents, activity feed, webhooks, templates CRUD (read-only here), settings write beyond read, letters, digital signature upload, postal mail (Pixelletter), encashment

*Last reviewed: 2026-07-20*

## How do you configure the Billomat DADL?

1. Log in to your Billomat account at https://{billomatID}.billomat.net
2. Open Settings > Employees (Einstellungen > Mitarbeiter) and select your user
3. Enable API access for the user — a personal API key is generated
4. Store it as CREDENTIAL_BILLOMAT_API_KEY in .env (sent as the X-BillomatApiKey header)
5. Note your billomatID (the subdomain in your Billomat URL) — it forms the base URL

**Environment variable:** `CREDENTIAL_BILLOMAT_API_KEY`

[Authentication docs](https://www.billomat.com/en/api/basics/authentication/)

*One credential is needed: CREDENTIAL_BILLOMAT_API_KEY (a person-bound API key from Settings > Employees). Replace YOUR_BILLOMAT_ID in the backends.yaml url with your account subdomain. Billomat has no OAuth scopes — the API key grants the issuing user's permissions, so restrict that user to limit API access. Optional: registering an App (Settings > Administration > Apps) yields an App-ID/App-Secret sent as separate X-AppId / X-AppSecret headers that only raise the rate limit (300 → plan quota per 15 min); adding those two credential-backed headers would need a small ToolMesh auth extension. A free developer account is available from api@billomat.com.
*

## How do you install the Billomat MCP server with ToolMesh?

Add to your `backends.yaml`:

```yaml
- name: billomat
  transport: rest
  dadl: billomat.dadl
  url: "https://YOUR_BILLOMAT_ID.billomat.net/api"

```

Set the credential:

```
CREDENTIAL_BILLOMAT_API_KEY=your-token-here
```

## What 145 tools does the Billomat DADL expose?

- **GET** `list_clients` — List clients (customers). Filter with name, client_number, email, country_code, note, tags, invoice_id, creditor_identifier. Returns an array of client objects (values are strings).

- **GET** `get_client` — Retrieve a single client by numeric ID
- **POST** `create_client` — Create a client. Wrap fields under the `client` key.

- **PUT** `update_client` — Update a client. Wrap changed fields under the `client` key (same fields as create_client).
- **DELETE** `delete_client` — Permanently delete a client. Fails if the client still has documents.
- **GET** `list_contacts` — List contacts for one client. client_id is REQUIRED — contacts are always scoped to a single client. Returns an array of contact objects.

- **GET** `get_contact` — Retrieve a single contact by ID
- **POST** `create_contact` — Create a contact for a client. Empty fields inherit the client's value.
- **PUT** `update_contact` — Update a contact (same fields as create_contact).
- **DELETE** `delete_contact` — Delete a contact
- **GET** `list_articles` — List catalog articles (products/services). Filter with article_number, title, description, currency_code, unit_id, supplier_id. Returns an array.

- **GET** `get_article` — Retrieve a single article by ID
- **POST** `create_article` — Create a catalog article.
- **PUT** `update_article` — Update an article (same fields as create_article).
- **DELETE** `delete_article` — Delete an article from the catalog
- **GET** `list_invoices` — List invoices. Filters: client_id, contact_id, invoice_number, status (DRAFT/OPEN/OVERDUE/PAID/CANCELED — comma-separated OR), payment_type, from, to (YYYY-MM-DD), label, intro, note, tags, article_id. group_by (client/status/day/week/month/year) returns aggregated sums instead. Returns an array of invoice objects (all values are strings).

- **GET** `get_invoice` — Retrieve a single invoice by ID (includes combined taxes and totals)
- **POST** `create_invoice` — Create an invoice (always DRAFT). Line items may be embedded. Call complete_invoice afterwards to assign a number and render the PDF.

- **PUT** `update_invoice` — Update an invoice. Only DRAFT invoices can be edited. Items are managed via invoice-items, not here.
- **DELETE** `delete_invoice` — Delete an invoice with all its documents (PDFs), items and comments. Irreversible.
- **PUT** `complete_invoice` — Complete a DRAFT invoice: assigns the final invoice number, renders the PDF and moves the status to OPEN (or OVERDUE/PAID). Optional template_id.

- **POST** `email_invoice` — Send the invoice to the client by e-mail. SIDE EFFECT: sends a real e-mail. recipients must contain at least one of to/cc/bcc.

- **PUT** `cancel_invoice` — Cancel a completed invoice (status -> CANCELED)
- **PUT** `uncancel_invoice` — Undo the cancellation of an invoice
- **GET** `get_invoice_pdf` — Get the invoice PDF metadata and content. Returns { base64file, filename, mimetype, filesize } — decode base64file to obtain the PDF bytes.

- **GET** `list_invoice_items` — List line items of an invoice. invoice_id is required. Returns an array ordered by position.
- **GET** `get_invoice_item` — Retrieve a single invoice line item by ID
- **POST** `create_invoice_item` — Add a line item to an existing invoice (DRAFT only).
- **PUT** `update_invoice_item` — Update an invoice line item (same fields as create_invoice_item, without invoice_id).
- **DELETE** `delete_invoice_item` — Delete an invoice line item
- **GET** `list_invoice_payments` — List payments booked against invoices. Filters: invoice_id, from, to, type (payment type, comma-OR), user_id. Returns an array.

- **GET** `get_invoice_payment` — Retrieve a single invoice payment by ID
- **POST** `create_invoice_payment` — Book a payment for an invoice (invoice must be OPEN or OVERDUE). Set mark_invoice_as_paid to also flip the invoice to PAID.

- **DELETE** `delete_invoice_payment` — Delete an invoice payment
- **GET** `list_invoice_comments` — List comments/activity-log entries of an invoice. invoice_id required. Returns an array.
- **POST** `create_invoice_comment` — Add a comment to an invoice's activity log.
- **DELETE** `delete_invoice_comment` — Delete an invoice comment
- **GET** `list_invoice_tags` — List tags of an invoice. invoice_id required. Returns an array.
- **POST** `create_invoice_tag` — Attach a tag to an invoice.
- **DELETE** `delete_invoice_tag` — Remove a tag from an invoice
- **GET** `list_recurrings` — List recurring invoice templates. Filters: client_id, contact_id, name, payment_type, cycle. Returns an array of recurring objects.

- **GET** `get_recurring` — Retrieve a single recurring invoice template by ID
- **POST** `create_recurring` — Create a recurring invoice template that auto-generates invoices on a cycle.
- **PUT** `update_recurring` — Update a recurring invoice template (same fields as create_recurring).
- **DELETE** `delete_recurring` — Delete a recurring invoice template
- **GET** `list_recurring_items` — List line items of a recurring template. recurring_id required. Returns an array.
- **GET** `get_recurring_item` — Retrieve a single recurring line item by ID
- **POST** `create_recurring_item` — Add a line item to a recurring template.
- **PUT** `update_recurring_item` — Update a recurring line item (same fields as create_recurring_item, without recurring_id).
- **DELETE** `delete_recurring_item` — Delete a recurring line item
- **GET** `list_offers` — List estimates (offers/quotes). Filters: client_id, contact_id, offer_number, status (DRAFT/OPEN/WON/LOST/CANCELED/CLEARED — comma-OR), from, to, label, intro, note, tags, article_id. Returns an array.

- **GET** `get_offer` — Retrieve a single estimate by ID
- **POST** `create_offer` — Create an estimate/offer (always DRAFT). Complete it to assign a number and render the PDF.
- **PUT** `update_offer` — Update an estimate (DRAFT only; same fields as create_offer).
- **DELETE** `delete_offer` — Delete an estimate with all items and comments
- **PUT** `complete_offer` — Complete a DRAFT estimate: assigns the number, renders the PDF, moves status to OPEN. Optional template_id.
- **POST** `email_offer` — Send the estimate to the client by e-mail. SIDE EFFECT: sends a real e-mail.
- **PUT** `cancel_offer` — Cancel an estimate (status -> CANCELED)
- **PUT** `uncancel_offer` — Undo the cancellation of an estimate
- **GET** `get_offer_pdf` — Get the estimate PDF: { base64file, filename, mimetype, filesize } — decode base64file.
- **GET** `list_offer_items` — List line items of an estimate. offer_id required. Returns an array.
- **GET** `get_offer_item` — Retrieve a single estimate line item by ID
- **POST** `create_offer_item` — Add a line item to an estimate.
- **PUT** `update_offer_item` — Update an estimate line item (same fields as create_offer_item, without offer_id).
- **DELETE** `delete_offer_item` — Delete an estimate line item
- **GET** `list_confirmations` — List order confirmations. Filters: client_id, contact_id, confirmation_number, status (DRAFT/OPEN/CANCELED/CLEARED), from, to, label, intro, note, tags, article_id. Returns an array.

- **GET** `get_confirmation` — Retrieve a single order confirmation by ID
- **POST** `create_confirmation` — Create an order confirmation (always DRAFT).
- **PUT** `update_confirmation` — Update an order confirmation (DRAFT only; same fields as create_confirmation).
- **DELETE** `delete_confirmation` — Delete an order confirmation with all items and comments
- **PUT** `complete_confirmation` — Complete a DRAFT confirmation: assigns the number, renders the PDF, moves status to OPEN.
- **POST** `email_confirmation` — Send the order confirmation by e-mail. SIDE EFFECT: sends a real e-mail.
- **PUT** `cancel_confirmation` — Cancel an order confirmation (status -> CANCELED)
- **GET** `get_confirmation_pdf` — Get the confirmation PDF: { base64file, filename, mimetype, filesize } — decode base64file.
- **GET** `list_confirmation_items` — List line items of an order confirmation. confirmation_id required. Returns an array.
- **GET** `get_confirmation_item` — Retrieve a single confirmation line item by ID
- **POST** `create_confirmation_item` — Add a line item to an order confirmation.
- **PUT** `update_confirmation_item` — Update a confirmation line item (same fields as create_confirmation_item, without confirmation_id).
- **DELETE** `delete_confirmation_item` — Delete a confirmation line item
- **GET** `list_credit_notes` — List credit notes. Filters: client_id, contact_id, credit_note_number, status (DRAFT/OPEN/PAID/CANCELED), from, to, label, intro, note, tags, article_id, invoice_id. Returns an array.

- **GET** `get_credit_note` — Retrieve a single credit note by ID
- **POST** `create_credit_note` — Create a credit note (always DRAFT). Optionally reference a source invoice via invoice_id.
- **PUT** `update_credit_note` — Update a credit note (DRAFT only; same fields as create_credit_note).
- **DELETE** `delete_credit_note` — Delete a credit note with all items and comments
- **PUT** `complete_credit_note` — Complete a DRAFT credit note: assigns the number, renders the PDF, moves status to OPEN.
- **POST** `email_credit_note` — Send the credit note by e-mail. SIDE EFFECT: sends a real e-mail.
- **GET** `get_credit_note_pdf` — Get the credit note PDF: { base64file, filename, mimetype, filesize } — decode base64file.
- **GET** `list_credit_note_items` — List line items of a credit note. credit_note_id required. Returns an array.
- **GET** `get_credit_note_item` — Retrieve a single credit note line item by ID
- **POST** `create_credit_note_item` — Add a line item to a credit note.
- **PUT** `update_credit_note_item` — Update a credit note line item (same fields as create_credit_note_item, without credit_note_id).
- **DELETE** `delete_credit_note_item` — Delete a credit note line item
- **GET** `list_delivery_notes` — List delivery notes. Filters: client_id, contact_id, delivery_note_number, status (DRAFT/OPEN/CANCELED), from, to, label, intro, note, tags, article_id, invoice_id. Returns an array.

- **GET** `get_delivery_note` — Retrieve a single delivery note by ID
- **POST** `create_delivery_note` — Create a delivery note (always DRAFT). Often created from an invoice via invoice_id.
- **PUT** `update_delivery_note` — Update a delivery note (DRAFT only; same fields as create_delivery_note).
- **DELETE** `delete_delivery_note` — Delete a delivery note with all items and comments
- **PUT** `complete_delivery_note` — Complete a DRAFT delivery note: assigns the number, renders the PDF, moves status to OPEN.
- **POST** `email_delivery_note` — Send the delivery note by e-mail. SIDE EFFECT: sends a real e-mail.
- **GET** `get_delivery_note_pdf` — Get the delivery note PDF: { base64file, filename, mimetype, filesize } — decode base64file.
- **GET** `list_delivery_note_items` — List line items of a delivery note. delivery_note_id required. Returns an array.
- **GET** `get_delivery_note_item` — Retrieve a single delivery note line item by ID
- **POST** `create_delivery_note_item` — Add a line item to a delivery note.
- **PUT** `update_delivery_note_item` — Update a delivery note line item (same fields as create_delivery_note_item, without delivery_note_id).
- **DELETE** `delete_delivery_note_item` — Delete a delivery note line item
- **GET** `list_reminders` — List dunning reminders for overdue invoices. Filters: client_id, contact_id, invoice_id, invoice_number, status (DRAFT/OPEN/CANCELED), from, to, label, intro, note. Returns an array.

- **GET** `get_reminder` — Retrieve a single dunning reminder by ID
- **POST** `create_reminder` — Create a dunning reminder for an overdue invoice (always DRAFT). The reminder level escalates automatically based on prior reminders.

- **PUT** `update_reminder` — Update a dunning reminder (DRAFT only; same fields as create_reminder).
- **DELETE** `delete_reminder` — Delete a dunning reminder
- **PUT** `complete_reminder` — Complete a DRAFT reminder: assigns the number, renders the PDF, moves status to OPEN.
- **POST** `email_reminder` — Send the dunning reminder by e-mail. SIDE EFFECT: sends a real e-mail.
- **GET** `get_reminder_pdf` — Get the reminder PDF: { base64file, filename, mimetype, filesize } — decode base64file.
- **GET** `list_suppliers` — List suppliers. Filters: name, supplier_number, email, country_code, note, tags. Returns an array.
- **GET** `get_supplier` — Retrieve a single supplier by ID
- **POST** `create_supplier` — Create a supplier (vendor for incoming invoices).
- **PUT** `update_supplier` — Update a supplier (same fields as create_supplier).
- **DELETE** `delete_supplier` — Delete a supplier
- **GET** `list_incomings` — List incoming invoices (expenses / supplier bills). Filters: supplier_id, number, status (paid/unpaid/overdue), from, to, tags. Returns an array.

- **GET** `get_incoming` — Retrieve a single incoming invoice by ID
- **POST** `create_incoming` — Record an incoming invoice (expense) from a supplier.
- **PUT** `update_incoming` — Update an incoming invoice (same fields as create_incoming).
- **DELETE** `delete_incoming` — Delete an incoming invoice
- **GET** `list_incoming_payments` — List payments made against incoming invoices. Filter with incoming_id. Returns an array.
- **POST** `create_incoming_payment` — Book a payment against an incoming invoice.
- **DELETE** `delete_incoming_payment` — Delete an incoming payment
- **GET** `list_taxes` — List configured tax rates. Returns an array of tax objects (name, rate, is_default).
- **GET** `get_tax` — Retrieve a single tax rate by ID
- **POST** `create_tax` — Create a tax rate.
- **PUT** `update_tax` — Update a tax rate (same fields as create_tax).
- **DELETE** `delete_tax` — Delete a tax rate
- **GET** `list_units` — List units of measure (e.g. hour, piece). Returns an array of unit objects.
- **GET** `get_unit` — Retrieve a single unit by ID
- **POST** `create_unit` — Create a unit of measure.
- **PUT** `update_unit` — Rename a unit of measure.
- **DELETE** `delete_unit` — Delete a unit of measure
- **GET** `list_templates` — List document (PDF) templates. Filter with type (INVOICE, OFFER, ...). Returns an array.
- **GET** `get_template` — Retrieve a single document template by ID
- **GET** `list_email_templates` — List e-mail templates used by the email_* actions. Returns an array.
- **GET** `get_email_template` — Retrieve a single e-mail template by ID
- **GET** `get_settings` — Retrieve the account settings (default number ranges, texts, due days, currency, tax defaults, etc.).
- **GET** `list_users` — List employees/users of the account. Returns an array of user objects.
- **GET** `get_user` — Retrieve a single user by ID
- **GET** `list_countries` — List countries with their tax/currency configuration. Returns an array.
- **GET** `list_currencies` — List configured currencies. Returns an array.

## Which DADLs are related to Billomat?

- [Xen Orchestra](https://www.dadl.ai/d/xen-orchestra/) — Xen Orchestra REST API (XO 6.4+, current through 6.6) -- complete coverage: VMs (incl. PATCH update + snapshot revert), VM controllers, hosts, pools, storage (SR, VDI incl. PATCH update, VBD), networks (VIF incl. PATCH update + PIF/PBD), VM/VDI snapshots, VM templates, hardware (PCI/PGPU/SM), tasks, backups (jobs/logs/writable repositories/restore), schedules, messages, alarms, events (SSE), RBAC v2 (users/groups/acl-roles/acl-privileges), proxies, servers, dashboards, auth tokens, SDN traffic rules (add/delete/update), health check
- [BookStack](https://www.dadl.ai/d/bookstack/) — BookStack wiki and documentation platform REST API -- shelves, books, chapters, pages (HTML/Markdown content), attachments, image gallery, comments, cross-entity search, exports (HTML/Markdown/PDF/ZIP), ZIP imports, users, roles, content permissions, recycle bin, audit log and tags. Hierarchy: shelves > books > chapters > pages.
- [Mempool](https://www.dadl.ai/d/mempool/) — mempool.space — Bitcoin block explorer, mempool visualizer, fee estimator, Lightning Network explorer, and transaction accelerator
- [NetBox](https://www.dadl.ai/d/netbox/) — NetBox DCIM/IPAM API -- full v4 coverage: sites, racks, devices, modules, interfaces, cables, power, IPAM (prefixes, IPs, VLANs, VRFs, route-targets, VLAN translation), virtualization, circuits (including virtual circuits), tenants, contacts, VPN (IKE/IPSec/L2VPN), wireless, extras (webhooks, event-rules, scripts, config-templates, bookmarks, notifications), users/permissions/tokens, and core data sources & jobs
- [Stripe](https://www.dadl.ai/d/stripe/) — Stripe REST API — payment processing, billing, subscriptions, invoices, products, and financial infrastructure
- [Zammad](https://www.dadl.ai/d/zammad/) — Zammad helpdesk REST API -- tickets, articles, users, organizations, groups, roles, knowledge base, SLAs, calendars, object manager (custom fields), macros, triggers, overviews, reports, time accounting, and full admin surface. Supports X-On-Behalf-Of impersonation on every endpoint.

---

**Canonical URL:** https://www.dadl.ai/d/billomat/
**Raw DADL:** https://github.com/DunkelCloud/dadl-registry/blob/main/billomat.dadl