Complete documentation

All help topics and API details are available on this page without selecting a topic. Availability depends on role, plan and company configuration.

Updated:

Sign in

Claribill offers two sign-in methods: Magic link (passwordless email sign-in) and Passkeys (fingerprint, facial recognition or device PIN).

Sign in with a magic link:

  1. Enter your email address on the sign-in page
  2. Click "Send magic link"
  3. Open the email and click the link
  4. You are signed in automatically

Magic link notes:

  • The link is valid for 24 hours and can only be used once
  • If you do not receive an email, check your spam folder
  • An account is created automatically when you sign in for the first time

Sign in with a passkey:

Passkeys let you sign in quickly without an email. A passkey is linked to your device or password manager.

  • Set up and manage passkeys under Settings → Security
  • You can have several passkeys per account, for example for a laptop and a phone
  • Email magic links remain available as a fallback

Open topic in help

Set up your company

After your first sign-in, a three-step onboarding flow helps you set up your company.

Step 1 – Company:

  • Select Legal form. For Sole proprietorship, enter the owner’s first and last name; Trading name (optional) can remain empty. For Registered sole proprietorship (e.U.), also enter the Registered company name. Other legal forms require a company name. Check the sender preview if it is shown.
  • Street, postcode, city and country are optional and can be added later

Step 2 – Tax and currency:

  • VAT ID is optional, for reverse charge and VIES validation
  • Tax number is optional
  • Currency: EUR, CHF, USD or GBP

Step 3 – Bank:

  • IBAN and BIC are optional and appear on your invoices

Tip:

The onboarding flow does not ask for a logo, bank name, phone number or website. You can add or change all details at any time under Settings → Company details.

Open topic in help

Dashboard and navigation

The Dashboard shows metrics for the active company and visible documents: revenue, receivables, master data, recurring revenue, monthly trend and top customers. Open amounts subtract recorded part payments. Proformas are excluded from invoice revenue; converted proformas do not request payment twice.

Finding your way

The sidebar groups invoicing, finances, master data, analysis, communication and administration. On small screens use the navigation toggle. Settings has its own submenu toggle. The outbox is directly in the sidebar. Open exports from reports and document templates from company details. Autosaved forms are at /en/dashboard/drafts.

The header offers language, company selection where applicable, notifications and the account menu. Signing out ends the session. Switching language does not translate customer data or document content.

Missing menu item

Check active company, membership role and plan. Visibility and permission to act are separate: a shared invoice does not automatically allow an employee to record a payment. What your role covers is set by your company under Settings → Roles & permissions; the categories selected for individual permissions and the role’s limit (“This role works in certain categories exclusively”) can restrict access further.

Light and dark appearance

Use the appearance icon in the header to switch between light and dark design. The label changes to offer the other appearance. This display setting does not change document contents.

Open support chat

Select Open support chat (the speech bubble) in the bottom-right corner and enter your question. Select Close support chat or press Escape to return to the page. Reopen the chat in the same area to continue the conversation. Reloading the page starts a new conversation.

Open topic in help

Create an invoice

  1. Open Invoices and New invoice.
  2. Choose the document type (invoice or proforma), customer, invoice date and due date. The customer selector also supports quick creation.
  3. Check document language, category, tax country and VAT treatment. Document language is independent of interface language.
  4. Add descriptions, quantities, units, prices and tax rates. Selecting a product copies its data; custom text remains possible.
  5. Add introductory text, closing text and internal notes as needed. Internal notes do not appear on the PDF.
  6. Advanced options include a custom document title, PDF without letterhead, invoice date as service date and a separate shipping address. Public-sector reference fields record order and buyer references, department, format, submission channel and status.
  7. Create invoice saves a draft; proformas use Create proforma. Finalise or send from the document page afterwards. Creating the draft does not send an email.

Ten line types

Product, service, percentage discount, absolute discount, shipping, advance payment, credit, text, subtotal and page break. Layout lines structure the PDF. Discounts reduce the tax base proportionally by rate. An advance-payment line does not replace a recorded payment.

Due date

The proposal uses the customer's payment term, then the company's, then 14 days from the invoice date. An explicitly changed due date is retained.

Article numbers

Enable Show article number in the document template settings reached from company details. Product SKUs are copied and can be edited on the document. Hiding the column does not delete stored numbers.

Format text

In fields with a formatting toolbar, select text and choose bold, italic or underline. Bulleted and numbered lists structure longer notes. Undo and redo apply to text editing. Check the document preview afterwards.

Open topic in help

Gross or net prices

Claribill calculates documents either with net prices (plus VAT, common for business customers) or with gross prices (including VAT, common for consumers, B2C). Every document and every item stores its own price mode.

Company default

Under Settings → Company details, Enter prices as in the Tax settings section defines which price mode new documents, recurring invoices and items start with. A later change only applies to new documents; existing documents keep their price mode.

Switch on the document

Under Advanced options at the end of the document (for recurring invoices under Optional details), choose Net or Gross under Prices; the company default is preselected. Switching keeps the entered unit prices unchanged; they then count as gross or net prices, and VAT and totals are recalculated. With gross prices, line discounts and the discount (€) are amounts including VAT as well; a discount (%) refers to the gross subtotal before it.

Items

An item's price applies in the item's price mode. When you add an item to a document with a different price mode, Claribill converts the price with the item's tax rate, rounded to the cent — for example €100.00 net at 20% becomes €120.00 gross. The Items & services list shows prices in the company's price mode, with the other price mode in small print below.

Rounding

With gross prices, the customer pays exactly the sum of the gross line amounts. VAT is extracted from the gross amount per tax rate. Example: 3 × €19.99 gross comes to €59.97, including €10.00 VAT (20%) and €49.97 net. An invoice with the converted net price of €16.66 would come to €59.98 instead.

What the PDF shows

Unit prices and line amounts are shown gross. The totals block lists the included VAT per tax rate (e.g. “Included VAT 20%”), together with the note “All prices include VAT.”.

Tax-exempt documents

Reverse charge, the small business scheme and other exemptions have no VAT. Gross and net are identical there, so both price modes calculate the same.

Conversions and follow-up documents

Conversions keep the price mode together with the prices: quote → order confirmation → invoice, order → invoice, pro forma → invoice, duplicate, cancellation and credit note for an invoice. Invoices generated from a recurring invoice take its price mode.

E-invoice, exports and reports

The e-invoice (Factur-X/ZUGFeRD) stays net-based: it contains the net line amounts and the VAT per tax rate exactly as on the PDF. The accounting export, DATEV, BMD, the VAT report and the VAT breakdown in the revenue report also work with net amounts and use the VAT per tax rate from the document.

REST API, MCP and AI assistant

When creating and updating invoices, credit notes with their own lines, quotes, order confirmations, orders, recurring invoices and items, the REST API accepts the field pricesIncludeTax (also prices_include_tax, only true or false). Without the field, the REST API always creates records with net prices, even if the company defaults to gross prices, because existing integrations send net prices. When updating without the field, the stored price mode is kept. Responses and webhooks contain pricesIncludeTax; the line amount lineTotal is always net. The MCP connection and the AI assistant use the company default when no value is given and show the price mode in the preview and confirmation.

Open topic in help

Invoice status

Each invoice can have one of these statuses:

StatusMeaning
DraftNot finalised; freely editable
FinalisedAn invoice number has been assigned, but the invoice has not been sent
SentSent to the customer and awaiting payment
PaidPaid in full
OverdueThe payment due date has passed
CancelledThe invoice has been cancelled

Status transitions:

  • Draft → Finalised, Sent or Cancelled
  • Finalised → Sent, back to Draft or Cancelled
  • Sent → Paid, Overdue or Cancelled
  • Overdue → Paid or Cancelled
  • Paid and Cancelled are final states: the status control does not allow a further transition

Correct a paid invoice:

A paid invoice cannot be cancelled directly. Use Create credit note to create a credit note that offsets the amount.

Failed delivery:

When sending a draft, Claribill assigns its invoice number before sending the email, so both the PDF and email carry it. If delivery fails (for example because of a sending limit or mail server error), the draft keeps that number and reuses it on retry. The number is never assigned a second time. This draft can no longer be deleted: send it again or cancel it to keep the numbering history complete. Cancelling it does not create a cancellation invoice because the original was never issued; its number remains recorded on the cancelled invoice.

Sending a cancelled invoice:

A cancelled invoice can still be sent by email if it was previously issued (a draft cancelled directly cannot). Its status remains cancelled, but it receives a sent date if it has none and appears in the audit log and email outbox.

Open topic in help

Download a PDF

Every invoice can be downloaded as a PDF.

Included information:

  • Your company details and logo
  • Customer address
  • Invoice number and date
  • Purchase order number and buyer reference or Leitweg-ID, if provided
  • All line items and tax rates
  • Net, VAT and gross totals
  • EPC QR code for a quick bank transfer
  • Bank details
  • Payment terms
  • Custom footer

Special cases:

  • Small business exemption: a reference to §6 Abs 1 Z 27 UStG
  • Reverse charge: a notice about the recipient's VAT liability
  • EU tax country: rates for all EU member states. For taxable sales, the delivery or customer country is suggested as the tax country, for example DE 19% / 7% or FR 20% / 10% / 5.5%
  • OSS (One-Stop-Shop): if the EU tax country differs from the company's country, the invoice is automatically marked as relevant for OSS and listed separately in the VAT report

Open topic in help

Recurring invoices

Automate regular invoices for subscriptions, maintenance contracts or rent.

Setup:

  1. Go to Recurring → New recurring invoice
  2. Select the customer
  3. Add the line items
  4. Choose an interval: weekly, every two weeks, monthly, quarterly, half-yearly or yearly
  5. Set a start date and, optionally, an end date
  6. Choose whether invoices should be emailed automatically

Automatic generation:

Invoices are created automatically at the scheduled time and can be sent by email.

Availability:

Recurring invoices are available from the Starter plan and are not included in Free.

Open topic in help

E-invoice (Factur-X/ZUGFeRD)

Claribill generates a separate XML export using the Factur-X/ZUGFeRD 2.3 BASIC profile (CII). Use the e-invoice XML action on an invoice. The regular PDF and XML are separate downloads; the invoice PDF does not currently embed XML as PDF/A-3.

Public-sector customers

Maintain the order reference, buyer reference and other submission information on the document. Selecting XRechnung, PEPPOL or a portal records the intended format or channel. It does not generate XRechnung or transmit to a portal or PEPPOL. Check the recipient's required format and submit the appropriate file yourself.

A proforma already converted into an invoice no longer requests payment and cannot export e-invoice XML.

Open topic in help

Versions and corrections

Sent and finalised invoices are locked to preserve the original record for GoBD purposes.

Locking:

Sending, finalising or first opening a distributable PDF can lock an invoice. A read-only preview is different. It can no longer be edited directly after that point.

Correction (§ 31 Abs. 5 UStDV / § 11 Abs. 12 UStG):

  • Start a Correction from the edit dialog of a locked invoice
  • Provide a reason with at least ten characters
  • A correction creates a new version (v2, v3, ...) while preserving the previous version unchanged

Version history:

The invoice detail page shows all previous versions and the reason for each correction.

Alternative:

A Credit note is often the simpler option for a cancellation or price adjustment.

Open topic in help

Proforma invoices

  1. Open Invoices → New invoice.
  2. Select the proforma document type.
  3. Enter customer, date, validity, lines and language, then create the proforma draft.
  4. Review it before finalising or sending through its document actions.

Proformas use their own PF numbering and are excluded from invoice revenue. Payments can be recorded subject to the usual payment permissions.

Conversion

Converting creates a linked invoice draft; the proforma keeps its PF number. Recorded payments and accepted bank matches transfer to the invoice. The new draft receives its RE number when issued. A fully paid draft is marked paid on finalisation.

If the proforma was only marked paid without a payment record, record the payment first. After conversion, continue on the linked invoice. The proforma is no longer resent, dunned, changed to another status or treated as an open receivable.

Open topic in help

Search, bulk actions and sending

In Invoices, combine search, dates, status, document type and category. Select rows using checkboxes to reveal bulk actions. Active filters or permissions may hide a document.

Download and print

Download multiple selected invoices as a ZIP file, or print a merged PDF. Use the document PDF actions for individual files. A detail preview differs from issuing a distributable document.

Sending

The bulk-send preview lists eligible and skipped invoices, reasons and remaining capacity. After confirmation, each eligible invoice uses the regular sending flow. The process stops at limits; inspect results and the outbox before retrying. Finalising or marking sent does not itself send an email.

Other actions

Status, category, deletion and SEPA actions depend on role, selection and document state. Drafts with an assigned invoice number cannot be deleted. Bulk actions do not bypass document visibility.

Open topic in help

Quotes

Create non-binding quotes for your customers using the same line item types as invoices.

Status:

  • Draft → Sent → manually set to Accepted or Rejected
  • Expired is displayed when the validity date has passed; the stored status does not change

Conversion:

A quote can be converted into an Invoice or Order confirmation as long as it has not been rejected or already converted.

Delivery:

Quotes are emailed to customers in the same way as invoices.

Validity:

A new quote suggests a 30-day validity period from the quote date, independently of the company payment term.

Existing order confirmation:

A quote with an existing order confirmation can still be converted to an invoice. Claribill identifies the existing confirmation first to help avoid billing the same service twice.

When converting to an invoice, the customer’s saved tax treatment and any custom exemption note are carried over. Check them on the invoice draft; without a customer default, the suggested tax treatment applies.

Open topic in help

Order confirmations

Confirm your acceptance of a customer's order in writing, either directly or from a quote.

Creation:

  • Create a new order confirmation directly, or
  • Use an existing Quote to copy its line items and customer details

Conversion:

  • Convert it into an Invoice when the work can be billed
  • The detail page does not currently offer conversion into an order. Create an order separately.

When converting to an invoice, the customer’s saved tax treatment and any custom exemption note are carried over. Check them on the invoice draft; without a customer default, the suggested tax treatment applies.

Open topic in help

Orders

Claribill provides an order document for long-term projects with multiple partial deliveries and invoices.

Creation:

  • Create an order using Orders → New order
  • Set the total budget, project start and planned end date

Order progress:

The detail page shows three progress bars:

  • Budget: the amount already invoiced relative to the total budget
  • Delivered: units delivered through linked delivery notes relative to the quantity ordered
  • Invoiced: the proportion of the order already invoiced

Links:

Delivery notes and invoices can be assigned to an order to keep its progress up to date automatically.

Open topic in help

Delivery notes

Document deliveries of goods without prices.

Line items:

Delivery notes contain only a description, quantity and unit — no prices.

Creation:

  1. Go to Delivery notes → New delivery note
  2. Select a customer and, optionally, the related order
  3. Enter the delivered items
  4. Save a draft or send the delivery note

Convert to an invoice:

You can create an invoice from a delivery note and add the missing prices and tax rates.

When converting to an invoice, the customer’s saved tax treatment and any custom exemption note are carried over. Check them on the invoice draft; without a customer default, the suggested tax treatment applies.

Open topic in help

Credit notes and cancellations

Credit notes offset invoice amounts for corrections, cancellations or standalone payouts.

Cancellation credit note:

When cancelling an issued invoice, the dialog lets you select creation of a cancellation credit note and its email delivery. Check both options before confirming. Cancelling a draft that was never issued does not create a cancellation credit note.

Partial credit note from an invoice:

Open a sent, paid or overdue invoice and click Create credit note. Select individual items and quantities for a partial credit note, or credit the entire invoice.

Standalone credit note:

For cases without a related invoice, such as commissions or payouts, use New credit note to create a standalone credit note.

Reason:

Every credit note requires a reason: cancellation, return, price correction, payout, commission, goodwill or other.

Permissions:

By default, owners, admins and finance users create credit notes. Under Settings → Roles & permissions this can be changed per role.

Credit notes count as invoices: which credit notes a member sees is determined by the permission Invoices: View of their role, including the categories selected there.

Edit a credit note

A standalone credit note uses the selected customer’s tax default and any exemption note. Open an editable credit note and choose Edit. Enter quantities and prices as positive amounts; the credit note is recorded with a negative sign. Choose Save changes. For a locked credit note, use the correction flow and Save correction.

Open topic in help

Customer management

Manage all your business customers in one place.

Create a customer:

  1. Go to Customers → New customer
  2. Enter a name or company name, email address and billing address
  3. Add a delivery address if needed
  4. For B2B customers, enter the VAT ID

VAT ID validation:

  • Click Check VAT ID to validate the number
  • Validation uses the EU VIES database
  • A valid VAT ID triggers a suggestion for the relevant tax treatment, such as reverse charge for an EU B2B transaction

DATEV integration:

You can assign each customer a Debtor account number for DATEV exports.

Temporary VAT validation outage:

If VIES is temporarily unavailable, Claribill displays “Validation currently unavailable” and retains the previously confirmed status.

Default document category:

Set a default document category on the customer to prefill new documents for that customer (see Document categories and access).

Open topic in help

Contacts

Store several contact people for each customer.

Contact details:

  • Name
  • Role or position
  • Email
  • Phone

Use:

  • Select a contact when emailing an invoice
  • Add CC/BCC recipients such as a tax adviser or finance team

Open topic in help

Create and use items

  1. Open Items & services → New item. If the list is empty, use Create your first item.
  2. Enter a name, optional description, price, tax rate, unit and optional SKU. Under Type, choose Product or Service. A flat fee can use a custom unit.
  3. Choose Create item. In the item row, choose Edit, then Save changes. Deactivate followed by Deactivate item removes it from future selections. Existing document lines keep their saved values.

The price is net or gross, depending on the item's price mode; new items start with the company default (see Gross or net prices).

Use an item in a document

Above or below the line items, choose Item and use Search items and services…. The item fills an empty last line; otherwise it is added as a new line. Selecting a template copies its name and description and the values used by this document, such as unit, item number and price. Check the line’s tax rate. Quantity is set separately.

Reuse a free line

Owners, administrators and finance users can choose Save as item on a free product or service line. Enter a description first: its first line becomes the item name and subsequent lines become its description. The saved item becomes available in the picker. Discounts and text-only lines cannot be saved as item templates.

Open topic in help

Record a payment

Record incoming payments against your invoices.

Record a payment:

  1. Open the invoice details
  2. Click Record payment
  3. Enter the amount and date
  4. Choose a method: bank transfer, cash, credit card, PayPal or other
  5. Add an optional reference, such as a transaction ID

Partial payments:

  • Several payments can be recorded against one invoice
  • The status changes to Paid only when the full amount has been paid

Overpayments:

An amount greater than the outstanding invoice balance is rejected. There is no credit balance account. Correct the payment or create a credit note if needed.

Permissions:

By default only owners, admins and finance users can record, change or delete payments, regardless of who created the invoice. These permissions can be changed per role under Settings → Roles & permissions.

Payment on a cancelled invoice:

Money received after cancellation can still be recorded manually or through bank matching. The invoice remains cancelled and does not change to Paid. An existing payment on a cancelled invoice can only be deleted, not edited.

Open topic in help

Bank reconciliation (finAPI)

Connect your business bank account to match incoming payments with outstanding invoices.

Setup:

  1. Go to Settings → Bank connection
  2. Connect your account through finAPI
  3. Claribill synchronises transactions regularly

Payment matching:

Under Payment matching, new bank transactions appear with automatic suggestions:

  • Accept: confirm the suggestion and record the payment automatically
  • Reject: discard the suggestion
  • Match manually: assign the transaction to another outstanding invoice, including a cancelled one (marked accordingly); the invoice remains cancelled and does not change to Paid

Renew consent:

Bank consent expires after a period of time and must be renewed under Settings → Bank connection.

Availability:

Bank integration is available from the Professional plan.

Open topic in help

SEPA direct debit

Claribill generates SEPA direct debit instructions in PAIN.008 XML format for import into your bank.

Requirements:

  • Save your Creditor ID under Settings → Bank details; Claribill validates its checksum
  • Save your company’s IBAN
  • The customer needs a valid IBAN and an active SEPA mandate under Edit customer → Bank details: mandate reference, signature date and type CORE or B2B. IBAN checksums are validated. Recurring collection is the default; a one-off mandate permits exactly one direct debit

Create a batch:

Select invoices in the invoice list and click SEPA direct debit. The preview shows the collections and explains why any invoices are excluded. Choose a collection date (tomorrow at the earliest), create the batch and download its PAIN.008 file. CORE and B2B collections receive separate batches and files.

  • Sent and overdue invoices in euros are collected for their remaining balance
  • Invoices already in a batch are excluded from subsequent exports
  • The preview warns about invoices not yet due on the collection date and archived customers; these invoices are still included
  • Invoice statuses remain unchanged; record payments as usual or through bank reconciliation
  • The invoice’s Payments section shows its collection batch

Manage batches:

Open SEPA direct debits from the sidebar or Reports to download a file again. Discard a batch only if its file was never submitted to the bank; its invoices can then be collected again.

Permissions:

Owners, admins and finance users can manage mandates and collect direct debits. Employees can only view mandates.

Open topic in help

Payment reminders

Claribill supports three reminder stages.

Stages:

  1. Payment reminder: a friendly reminder after the due date
  2. First formal reminder: a formal reminder with a deadline
  3. Second formal reminder: a final reminder before legal action

Configuration under Settings:

  • Reminder fee per stage (€)
  • Late-payment interest (% per year)

Automatic calculations:

  • Interest is calculated per day
  • Reminder fees are added automatically

Delivery:

  • Emails use text appropriate to the stage
  • The reminder history is recorded

Limits

Overdue detection does not automatically send reminders. Open the send-reminder dialogue to send one. Credit notes and converted proformas cannot be dunned. The reminder is an email with an amount breakdown; no separate reminder PDF is currently generated. Fees use the invoice currency.

Open topic in help

Document storage

Open Documents and the upload dialogue. Select the file, document type, description and optional tags, customer or invoice. Search, filter, download, archive, restore or delete according to your permissions.

Files and limits

Direct upload supports files up to 100 MB, subject to storage allowance. If direct storage is unavailable, the UI's small server fallback allows at most 4 MB. Supported formats are PDF, PNG, JPEG, GIF, WebP, DOC/DOCX, XLS/XLSX, TXT and CSV.

Visibility

Company, role, creator, sharing and category access determine visibility. Archiving retains the file; deletion removes it. Storage does not promise indefinite retention regardless of deletion or contract.

Assistant files

Assistant attachments are kept separately in the AI assistant folder and conversation subfolders. Chat uploads have their own smaller limits. Deleting a conversation also removes its files.

Open topic in help

Document categories and access

Owners and admins manage categories with names and colours under Settings → Document categories, edit or archive them and inspect uncategorised documents. Each document has at most one optional category. Combine category, date, status and text filters.

Access through roles

Categories belong to the role, not to the individual member. Under Settings → Roles & permissions, for permissions with a scope you set the level Categories and select, right in the permission's row, the categories that permission applies to. Each permission has its own selection: you can view invoices in categories A and B but edit them only in B. See the “Roles & permissions” section for details. Anyone who may manage roles and permissions can also get there from Settings → Document categories with the button Open Roles & permissions in the page header. The role overview shows for each role on how many permissions categories are selected and whether the role works in certain categories exclusively.

A permission only reaches documents without a category if the entry Documents without a category is selected in its selection. With the card Limit the role’s working area and the option This role works in certain categories exclusively, documents outside the limit are locked, including the member's own and shared ones; sharing does not bypass this.

Previous access per team member

If your company still has settings from the earlier per-member access management, the card Previous access per team member appears. That access keeps working unchanged but can no longer be edited. Anyone who may manage roles and permissions transfers it with Transfer to roles: if all members of a role have the same selection, the role takes it over; otherwise a separate role is created per selection (“Role – Categories”) and the members move there. Nobody sees more or less afterwards.

Customer defaults and bulk changes

A customer's default category prefills new documents unless a category was explicitly selected. Authorised users can change the category of selected invoices together. Archived categories remain recorded on existing documents.

Open topic in help

Document templates

Open company details in Settings, then Document templates. Owners and admins edit printed invoice defaults separately for German and English. The current screen does not offer a general selector for every document type.

  1. Select the template's content language.
  2. Edit introductory and closing text using the rich-text editor and placeholder picker, for example {rechnungsnummer}.
  3. Enable Show article number when the column should appear in document lines and PDFs.
  4. Save or discard changes before switching template language.

Custom text is not automatically translated. Intentionally empty text stays empty. Template changes do not rewrite existing documents or archived version PDFs. Product SKUs are copied into document lines and remain stored when the column is hidden.

Open topic in help

Filename configuration

Choose the PDF filenames used for downloads and email attachments.

Configuration:

  1. Go to Settings → Filenames
  2. Define a pattern for each document type using placeholders, for example Invoice-{rechnungsnummer}
  3. A live preview shows the resulting filename using sample data

Default:

Without a custom pattern, the document number is used as the filename.

Open topic in help

Revenue report

Find detailed reporting under Reports.

Period selection:

Choose the reporting period:

  • Year: a full-year overview
  • Quarter: Q1 (Jan–Mar), Q2 (Apr–Jun), Q3 (Jul–Sep), Q4 (Oct–Dec)
  • Month: individual months

Available metrics:

  • Invoice revenue, gross and net
  • Paid invoices
  • Outstanding receivables, less recorded partial payments
  • Incoming payments
  • Average invoice value
  • Payment rate
  • Average time to payment, in days until the first payment
  • Year-on-year comparison, as a percentage change

VAT breakdown:

Amounts are grouped by tax country, tax rate and exempt cases:

  • AT: 20%, 13%, 10%, 0%
  • DE: 19%, 7%, 0%
  • Other EU countries at their respective rates, with OSS sales shown separately
  • Exempt or out-of-scope cases such as reverse charge or exports

Monthly trend:

A bar chart provides a twelve-month overview in the annual view.

Open topic in help

Exports

Export your data for accounting.

Available formats:

CSV export

  • A general-purpose format
  • For Excel and Google Sheets
  • All invoice data

DATEV export

  • Posting batch format
  • Directly importable into DATEV
  • Includes debtor account numbers

BMD export

  • Postings and customer/supplier accounts for your tax adviser using BMD NTCS
  • Provided as a ZIP file

VAT report

  • Summary by tax country, tax rate and tax treatment
  • For your tax return
  • Net, VAT and gross amounts per rate

Documents with gross prices export net amounts and the VAT per tax rate exactly as shown on the document (see Gross or net prices).

Period:

Choose a month, quarter or full year.

Availability:

CSV exports and VAT reports are available on every plan. DATEV and BMD exports require the Starter plan or above.

Open topic in help

Audit log

Owners and admins open Audit log to inspect recorded events, their time, user, object and, where available, details and before/after values. Not every event has an IP address or complete field comparison.

Tabs filter by object type, such as invoices, customers or payments. All clears the type filter. Pages contain 50 entries; pagination opens older events. Open available details to compare changes. API actions have corresponding labels. Names and free text remain in their original language.

The audit log supports traceability; it is not a blanket promise that every action is recorded completely or immutably.

Open topic in help

Company details

Manage your company information under Settings.

Basic details:

  • Company name
  • Address
  • VAT ID
  • Currency: EUR, CHF or USD
  • Additional lines in the document header: up to 5 freely named lines (label and value) printed in the letterhead of all documents below the tax number and VAT ID, e.g. the inspection body code of an organic farm (“Bio-Kontrollstelle: AT-BIO-301”). Without a label, only the value is printed.

Bank details:

  • Account holder
  • IBAN
  • BIC
  • Bank name

These details appear on your invoices and are used for the EPC QR code.

Payment terms:

  • Default payment term in days
  • Early-payment discount (%) and discount period

Tax settings:

  • Enable or disable the Small business exemption

Other settings:

  • Brand colours: primary and accent colours for PDFs
  • Number ranges: configure formats and starting numbers

Custom footer:

The document footer holds up to 6 lines in total. The form shows how many lines the company details use and how many remain for your own text.

Select Legal form. For Sole proprietorship, enter the owner’s first and last name; Trading name (optional) can remain empty. For Registered sole proprietorship (e.U.), also enter the Registered company name. Other legal forms require a company name. Check the sender preview if it is shown.

For document emails sent from the default Claribill address, replies go to the valid external company email in Settings → Company details. Check that address if your customers cannot reply to the intended mailbox.

Open topic in help

Language and document templates

Interface and documents

The interface language and a document's language are independent. Switching between German and English does not translate your own line-item text, customer details or previously issued documents.

Language of new documents

Choose the default language for new documents under Settings. A customer can have a specific document language or inherit the company setting.

When creating a document, you can explicitly select German or English. Without an explicit choice, the customer's preference takes priority over the company setting. An explicit choice is retained when you select another customer.

Follow-up documents and recurring invoices

Copies, conversions, cancellations and linked credit notes inherit the source document's language. Existing recurring schedules retain their saved language profile. Changing a company or customer preference does not change these documents retrospectively.

Your own text

Printed invoice templates and email templates are maintained separately for German and English. Review your English templates before your first English delivery. Your own text is not translated automatically; intentionally empty invoice text stays empty.

When sending a document, its saved language and the matching template determine the content. The interface language of the person who clicks Send does not change the document's language.

Open topic in help

Upload a logo

Upload your logo for your invoices.

Requirements:

  • Format: PNG, JPEG or SVG
  • Maximum size: 500 KB
  • Recommended dimensions: 300 × 100 pixels

Use:

  • Appears at the top left of PDFs
  • Scales automatically

Open topic in help

Brand colours

Match document colours to your company branding.

Available colours:

  • Primary colour: headings and important elements
  • Accent colour: secondary elements and amounts

Configuration:

  1. Go to Settings
  2. Scroll to Brand colours
  3. Use the colour picker or enter hexadecimal values
  4. The Live preview shows how your invoices will look

Use:

The selected colours are used in generated PDFs:

  • Invoices
  • Quotes
  • Delivery notes

Open topic in help

Number ranges

Configure document number formats and sequences.

Settings → Number ranges:

Number format:

Choose one of six formats or define your own:

  • RE-2025-0001: prefix, year and number
  • RE20250001: compact, without separators
  • 2025-0001: year and number only
  • RE/2025/0001: with slashes
  • 202501-0001: year, month and number
  • 25010001: short year, month and number
  • Custom format: your own pattern

Number length:

  • Choose three to eight digits, from 001 to 00000001
  • Default: four digits, 0001

Annual reset:

When enabled, numbering starts again from the starting number each year. This is recommended for Austrian companies.

Document types:

Configure starting numbers separately for:

  • RE: invoices
  • GS: credit notes and cancellations
  • PF: proforma invoices
  • AN: quotes
  • AB: order confirmations
  • AU: orders
  • LS: delivery notes

Preview:

The live preview shows the next document number for each type.

Open topic in help

API keys and authentication

API keys and authentication

The REST API v1 is available at https://www.claribill.com/api/v1. Its machine-readable description is available at /openapi.json. See the API reference for all endpoints and fields.

Authentication

Send the API key in the Authorization header:

Authorization: Bearer sk_live_...

Create a key under Settings → API keys. This requires the “API keys” permission (owners and administrators by default).

A key is not bound to a user, a role or document categories: within its scopes it reaches every document of the company, regardless of the role and categories of the person who creates it.

Where an action needs an acting user (for example as the creator of a document), the company’s owner is used; with several owners, the one with the oldest membership. The audit log marks such actions as API actions and names the key used.

  1. Validate the Bearer header (401 for a missing/invalid header or unknown key).
  2. Check the apiAccess plan gate and reserve monthly quota as an ApiLog entry (403 code: "plan_no_access", 429 code: "quota_exceeded").
  3. Check the route's required scopes against the key's scopes (403 with requiredScopes if missing).
  4. Check the per-key rate limit (429, only with configured Upstash).

Plan access and monthly quota

API access requires the apiAccess feature (STARTER, PROFESSIONAL, ENTERPRISE). Monthly quota: STARTER: 10,000 calls/month, PROFESSIONAL: 50,000 calls/month, ENTERPRISE: 250,000 calls/month. When exhausted, the API responds with 429 and code: "quota_exceeded".

Rate limit

100 requests/minute per API key. Active only when Upstash (Redis) is configured. Quota reservations are released again for 403/429 responses.

Response envelope

All v1 endpoints that return data wrap the payload in { data: … }. List endpoints also return { data: [...], pagination: { total, limit, offset, hasMore } } (or meta for some resources). Successful actions without a return object respond with { success: true }. Blog routes under /api/v1/blog/** (platform admins only) are an exception: lists use their own key ({ posts }, { categories }, { tags }, { media }), individual objects have no envelope, AI jobs use { job } and deletions return { ok: true }.

  • Single object: { data: { id, ... } }
  • List: { data: [ { id, ... }, ... ], pagination: { total, limit, offset, hasMore } }
  • Action without a return object: { success: true }

Pagination

All list endpoints support the same pagination:

  • limit — Page size (Default: 50)
  • offset — Offset (Default: 0)

Maximum limit: 100. { pagination: { total, limit, offset, hasMore } } (some older resources also include has_more or use the key meta instead of pagination; see the relevant endpoint).

Error format

{ error: string, code?: string, allowedValues?: string[] }
StatusMeaning
400Invalid input: required field, enum value, number/date format or business rule.
401Authorization header missing, not a Bearer header, or the key is invalid/inactive.
403Missing scope (requiredScopes in the response), plan without API access (code: "plan_no_access"), or a plan limit is exhausted.
404The record does not exist or belongs to another company. Other companies' data is never returned.
409State conflict: incorrect status for the action, concurrent change, or a number/reference already taken.
429Monthly quota exhausted (code: "quota_exceeded") or rate limit reached.
500Unexpected internal error.
502A dependent external service failed, such as email delivery or S3.

Naming conventions

Request bodies generally accept both camelCase and snake_case for the same field, for example customerNumber = customer_number.

Responses using camelCase throughout: invoices (core routes, versions, corrections), quotes, order-confirmations, delivery-notes, orders, recurring-schedules, documents, products, company

Responses retaining snake_case for compatibility: customers (camelCase with individual snake_case aliases such as tax_id, created_at), credit-notes (snake_case throughout, with camelCase aliases for new fields), invoice payments & dunning (snake_case, with camelCase aliases for new fields), webhooks (snake_case)

Permissions (scopes)

Each API key is assigned individual scopes when created:

ScopeLabelDescription
invoices:readRead invoicesRead invoices, credit notes, payments and reminder status; retrieve PDFs
invoices:writeEdit invoicesCreate, update and send invoices and credit notes; record payments and reminders
customers:readRead customersAccess customer lists and details
customers:writeEdit customersCreate, update, archive and delete customers
products:readRead productsAccess product lists
products:writeEdit productsCreate and update products
quotes:readRead quotesRead quotes and their PDFs
quotes:writeEdit quotesCreate, update, send and convert quotes
order-confirmations:readRead order confirmationsRead order confirmations and their PDFs
order-confirmations:writeEdit order confirmationsCreate, update, send and convert order confirmations
delivery-notes:readRead delivery notesRead delivery notes and their PDFs
delivery-notes:writeEdit delivery notesCreate, update and send delivery notes; convert them to invoices
orders:readRead ordersRead orders, quantities and statistics
orders:writeEdit ordersCreate and update orders; manage quantities
recurring:readRead recurring invoicesRead recurring invoice schedules
recurring:writeEdit recurring invoicesCreate, update and pause schedules; generate invoices from them
documents:readRead documentsRead document storage and download files
documents:writeEdit documentsUpload, update, archive and delete documents
exports:readExportsGenerate accounting exports (CSV, DATEV, BMD, VAT return) and customer CSV
direct-debits:writeCreate SEPA direct debitsCreate SEPA batches and their direct debit files (PAIN.008); the invoices are blocked from further exports until the batch is discarded
company:readRead company detailsRead company details, number ranges and plan features
webhooks:readRead webhooksRead webhook endpoints and deliveries
webhooks:writeManage webhooksCreate, update and delete webhook endpoints

The additional scopes blog:read, blog:write, blog:publish, blog:moderate belong to the internal blog CMS. They are reserved for platform admins and cannot be assigned to regular companies.

Webhook events (Enterprise plan)

Webhook endpoints can subscribe to the following events; WEBHOOK_TEST is only sent by the test delivery and cannot be subscribed to. See the Webhooks resource in the API reference for details.

EventTrigger
INVOICE_CREATEDInvoice created through a dashboard action or POST /api/v1/invoices.
INVOICE_UPDATEDInvoice changed without a status transition (PUT /api/v1/invoices/{id}).
INVOICE_SENTInvoice emailed to the customer.
INVOICE_PAIDPayment recorded that settles an invoice in full.
INVOICE_OVERDUEAn unpaid invoice passes its due date.
INVOICE_CANCELLEDInvoice or credit note cancelled.
CREDIT_NOTE_CREATEDCredit note created.
CREDIT_NOTE_PAIDCredit note payout executed.
PAYOUT_APPROVEDCredit note payout approved for execution.
PAYOUT_EXECUTEDPayout executed successfully.
PAYOUT_FAILEDPayout execution failed.
PAYOUT_CANCELLEDPayout cancelled before execution.
CUSTOMER_CREATEDCustomer created.
CUSTOMER_UPDATEDCustomer updated.
CUSTOMER_DELETEDCustomer deleted.
REMINDER_SENTPayment reminder or formal reminder sent.
REMINDER_ESCALATEDReminder escalated to the next stage.
BLOG_POST_CREATEDPlatformBlog post created, platform blog only.
BLOG_POST_UPDATEDPlatformBlog post updated, platform blog only.
BLOG_POST_PUBLISHEDPlatformBlog post published or scheduled publication triggered, platform blog only.
BLOG_POST_UNPUBLISHEDPlatformBlog post unpublished/archived, platform blog only.
BLOG_COMMENT_CREATEDPlatformNew blog comment submitted, platform blog only.
BLOG_COMMENT_APPROVEDPlatformBlog comment approved/moderated, platform blog only.
WEBHOOK_TESTTest event from POST /api/v1/webhooks/{id}/test, without a business object. Cannot be subscribed to; the receiver acknowledges it without processing.

MCP / Codex plugin

An MCP plugin lets AI assistants such as Codex create invoice drafts in chat. See Claribill in Codex for details.

Open topic in help

Email templates

Customise the text of automatically sent emails.

Available templates:

TemplateUse
Invoice emailSending invoices
Credit note emailSending credit notes
Proforma emailSending proforma invoices
Quote emailSending quotes
Order confirmation emailSending order confirmations
Delivery note emailSending delivery notes
Payment reminderThe first friendly reminder
First formal reminderA formal reminder
Second formal reminderThe final reminder before legal action

These templates apply to the relevant document type in the dashboard, REST API and recurring invoice delivery. The default text is used when no custom template is configured.

For reminders, the body appears before the invoice breakdown and the closing text after it. Claribill supplies invoice details, fees, bank details and the standard notes about payments already made and contacting the sender.

Team invitations have their own custom template; cancellation invoices use the credit-note template.

Placeholders:

Dynamic placeholders are replaced automatically:

  • {companyName}: your company name
  • {invoiceNumber}: invoice number
  • {grossTotal}: gross amount
  • {dueDate}: due date
  • {customerName}: customer name
  • {daysPastDue}: days overdue, for reminders

The editing screen lists the placeholders supported by each template.

Editing:

  1. Go to Settings → Email templates
  2. Select a template
  3. Edit the subject, greeting, body and signature
  4. Save your changes

Every template can be reset to its default at any time.

Subject rule:

A custom subject must contain the document number using {invoiceNumber} or {documentNumber}, depending on the document type.

Sending limits:

To protect against abuse, Claribill limits email to external recipients to 10 per hour and 30 per day during a company’s first 30 days, then 50 per hour and 200 per day. Emails to your own verified team do not count. When a limit is reached, sending fails with an explanatory message.

Current template behaviour

Team invitations also use custom templates. Cancellation emails use the credit-note template. Maintain German and English separately; the saved document or invitation language chooses the template. Inactive templates fall back to the default in that same language.

Open topic in help

Custom email domain

Send emails from your own domain instead of claribill.com.

Benefits:

  • Use your company domain for a professional appearance
  • DKIM signing helps deliverability
  • Customers recognise your sender domain

Setup:

  1. Go to Settings → Email domain
  2. Enter your domain, for example musterfirma.at
  3. Choose a sender name and email address, for example rechnung
  4. Click Set up domain
  5. Add the displayed DNS records at your domain provider

DNS records in detail

After setup, the page shows five DNS records to add at your domain provider, such as Hetzner, IONOS, all-inkl or Cloudflare.

1. Domain verification (TXT record)

FieldValue
TypeTXT
Name/host_amazonses.ihredomain.at
Value/contentThe displayed verification token, a long string
TTL300 or the default

Example:

Name:  _amazonses.musterfirma.at
Value: abc123def456xyz789...

2. DKIM signature (three CNAME records)

DKIM helps verify that emails originate from your domain. You receive three separate CNAME records:

FieldValue
TypeCNAME
Name/host[token1]._domainkey.ihredomain.at
Target/value[token1].dkim.amazonses.com

Example for all three records:

Name:   abc123._domainkey.musterfirma.at
Target: abc123.dkim.amazonses.com

Name:   def456._domainkey.musterfirma.at
Target: def456.dkim.amazonses.com

Name:   ghi789._domainkey.musterfirma.at
Target: ghi789.dkim.amazonses.com

3. SPF record (optional, recommended)

FieldValue
TypeTXT
Name/hostihredomain.at or @
Value/contentv=spf1 include:amazonses.com ~all

Note: If you already have an SPF record, add include:amazonses.com before ~all or -all:

Before: v=spf1 include:_spf.google.com ~all
After:  v=spf1 include:_spf.google.com include:amazonses.com ~all

Where to find DNS settings

ProviderPath
HetznerDNS Console → Select zone → Records
IONOSDomains → DNS settings
all-inklKAS → Domain → DNS settings
CloudflareDNS → Records
StratoDomain management → DNS management
HostpointControl Panel → DNS Zone

Check verification

  • DNS changes can take up to 48 hours, though they are usually faster
  • Click Check status to see the current result
  • ✅ Domain verified + ✅ DKIM verified means emails are sent from your domain

Common errors:

  • Copy-and-paste mistakes, including invisible spaces
  • The wrong record type, such as TXT instead of CNAME
  • A trailing dot in the hostname: requirements vary by provider
  • A TTL that is too high; the default usually works

Availability:

Custom domains and SMTP servers require the Professional plan or above. Without this plan feature, Claribill continues to use its own sender.

Open topic in help

CSV import

Import customers and products from CSV files.

Supported imports:

  • Customers: around 30 columns, including customer number, name/company, salutation, address, VAT ID, tax number, bank details, payment terms, early-payment discount, note and group
  • Items & services: name, price, tax rate, unit, SKU and service flag

CSV format:

  • UTF-8 encoding
  • Column names in the first row
  • Comma or semicolon delimiter, detected automatically
  • Quote text containing special characters

Column mapping:

After uploading, map your file's columns to Claribill fields before starting the import.

Notes:

  • Maximum 1,000 rows per import
  • Duplicates are skipped based on email address or SKU
  • Errors are shown in detail

Availability:

CSV import requires the Starter plan or above. Customer imports only add as many customers as the plan allows; surplus rows are reported as errors.

For an item import, select Items & services. After previewing your data, select Import items and then Open item list to review the result.

Open topic in help

API reference

API reference

API explorer

All REST API v1 resources, endpoints, fields and side effects come from the same catalogue as the OpenAPI document.

Invoices24 endpoints · invoices:read, invoices:write

Invoices and proformas, including payments, reminders, corrections, versions and Factur-X/ZUGFeRD export.

MethodPathScopeSummary
POST/api/v1/invoices/prepareinvoices:read, customers:readPrepare REST creation intent without business writes
GET/api/v1/invoicesinvoices:readList invoices, including credit notes and proformas
POST/api/v1/invoicesinvoices:writeCreate an invoice or proforma as a draft
GET/api/v1/invoices/{id}invoices:readRead invoice details
PUT/api/v1/invoices/{id}invoices:writeUpdate an invoice and/or change its status
DELETE/api/v1/invoices/{id}invoices:writeDelete an invoice draft
GET/api/v1/invoices/{id}/pdfinvoices:readDownload an invoice PDF
GET/api/v1/invoices/send-capabilityinvoices:writeCheck opt-in send capability
GET/api/v1/invoices/{id}/send-statusinvoices:writeRead historical opt-in send status
POST/api/v1/invoices/{id}/sendinvoices:writeSend an invoice by email
POST/api/v1/invoices/{id}/cancelinvoices:writeCancel an invoice, optionally creating a cancellation credit note
POST/api/v1/invoices/{id}/stornoinvoices:writeCreate a cancellation credit note for an already cancelled invoice
POST/api/v1/invoices/{id}/duplicateinvoices:writeDuplicate an invoice as a new draft
POST/api/v1/invoices/{id}/convertinvoices:writeConvert a proforma to a regular invoice
GET/api/v1/invoices/{id}/paymentsinvoices:readList an invoice's payments
POST/api/v1/invoices/{id}/paymentsinvoices:writeRecord an invoice payment
PUT/api/v1/invoices/{id}/payments/{paymentId}invoices:writeUpdate a payment
DELETE/api/v1/invoices/{id}/payments/{paymentId}invoices:writeDelete a payment
GET/api/v1/invoices/{id}/dunninginvoices:readRead reminder status and history
POST/api/v1/invoices/{id}/dunninginvoices:writePause or resume reminders, or send a reminder stage
POST/api/v1/invoices/{id}/correctinvoices:writeCreate a correction under § 31 Abs. 5 UStDV as a new version
GET/api/v1/invoices/{id}/versionsinvoices:readRead an invoice's version history
GET/api/v1/invoices/{id}/versions/{version}/pdfinvoices:readDownload the archived PDF of a specific version
GET/api/v1/invoices/{id}/facturxinvoices:readDownload Factur-X/ZUGFeRD XML
POST/api/v1/invoices/prepare— Prepare REST creation intent without business writes

Scope: invoices:readcustomers:read

Body fields

FieldTypeRequiredDefaultDescription
preparation_versionnumberno–Only for create_body from POST /invoices/prepare: version 1 binds the complete creation intent; unknown version → 409. Without this field the existing Create contract remains unchanged.
documentTextVersionnumberno–With preparation_version: required value 1; another text version → 409.
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–Must belong to the company
linesLineInput[]yes–At least one line item
invoiceType / invoice_typestring (Enum)noINVOICECREDIT_NOTE → 400, with a reference to POST /api/v1/credit-notesINVOICE | PROFORMA
issueDateISO datenotodayInvoice date
dueDateISO datenocustomer.paymentTermDays ?? company.paymentTermDays ?? 14 daysDue date
servicePeriodStart / servicePeriodEndISO date | nullno–Service period
currencystringnoEURCurrency code
reverseChargebooleannofalseVAT liability of the recipient
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.
taxExemptionReasonstring (Enum)no–Invalid → 400NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringno–Free text about the exemption
taxCountry / deliveryCountrystring (ISO-2)no–Tax or delivery country
ossApplicable / oss_applicablebooleanno–If omitted, OSS is derived from the tax context
ossCountry / oss_countrystring (ISO-2)no–OSS destination country
notesstringno–Internal note, not printed
footerstringno–Closing text (printed)
headerText / header_textstring (HTML)no–Opening text (printed)
customTitle / custom_titlestringno–Custom document title instead of Invoice
pdfWithoutLetterhead / pdf_without_letterheadbooleannofalsePDF without letterhead
invoiceDateIsServiceDate / invoice_date_is_service_datebooleannofalseInvoice date equals service date
useShippingAddress / use_shipping_addressbooleannofalseEnables shippingName/-Street/-ZipCode/-City/-Country
documentCategoryId / document_category_idstring | nullno–Document category
orderNumber / order_numberstringno–Purchase order number/order reference
buyerReference / buyer_referencestringno–Buyer reference or Leitweg-ID
eInvoiceAudit / e_invoiceobjectno–Audit data for format, submission channel, portal URL and status
metadataobjectno–Custom JSON object
lines[].descriptionstringno–Line item description
lines[].quantitynumberno1Quantity
lines[].unitPrice / unit_pricenumberno0Unit price in the document's price mode (net, or gross with pricesIncludeTax)
lines[].taxRate / tax_ratenumbernoStandard rate of the tax countryTax rate in %
lines[].discountnumberno0Absolute discount amount, not a percentage
lines[].unitstring | nullno–Processed only in a prepared body: binds the unit including the existing column default Stk. Ordinary Create bodies keep their existing behaviour.
lines[].lineType / line_typestring (Enum)noPRODUCTLine item typePRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Response: 200 { data: InvoicePreparation }

  • Same REST parser and Create core, consistent Repeatable-Read snapshot of customer, company and INVOICE language templates. POST keeps private document text out of URL logs; response Cache-Control: no-store.
  • Store create_body once before the first Create: language/text version, text/null/empty, dates/due date, EUR default, lines, tax and OSS are explicitly bound. Reuse the same JSON bytes with OriginalKey; do not prepare an old claim again.
  • No invoice, number, audit, payout, email, PDF, S3 or business webhook action. Existing API-key usage and ApiLog/monthly quota remain operational effects. Permissions, plan, category and customer ownership are checked again at Create; preparation reserves nothing.
  • No snapshot of later PDF/email rendering or master-data addresses and no send idempotency. Existing Create key at least 30 days, conservative CMM recovery window at most 24 hours; legacy claims without the original body remain unclear.
GET/api/v1/invoices— List invoices, including credit notes and proformas

Scope: invoices:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–Filter by status, case-insensitiveDRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
invoice_type / invoiceTypestring (Enum)no–Filter by document typeINVOICE | CREDIT_NOTE | PROFORMA
customer_id / customerIdstringno–Filter by customer
searchstringno–Case-insensitive partial match on document number or customer name
fromISO dateno–issueDate ≥ from
toISO dateno–issueDate ≤ to
category_idstring | "uncategorized"no–Filter by document category
limitnumberno50Page size
offsetnumberno0Offset

Response: { data: Invoice[], pagination }. Includes credit notes and proformas when invoice_type is omitted. Sorted by issueDate descending.

  • All queries are scoped to the API key's company.
  • Invalid status/invoice_type → 400 with allowedValues.
POST/api/v1/invoices— Create an invoice or proforma as a draft

Scope: invoices:write

HTTP headers

FieldTypeRequiredDefaultDescription
Idempotency-Keystringno–Optional, 8–200 characters from A–Z, a–z, 0–9, . _ : -. Reusing the same key and body returns the same invoice in its current state (201, Idempotent-Replayed: true header), instead of creating another. The same key with a different body returns 422 idempotency_key_reused. The entire body is compared, including fields the server does not use. Keys are scoped to the company; concurrent calls with the same key create exactly one invoice. A key remains effective for at least 30 days. After deletion, reusing it creates a new invoice.

Body fields

FieldTypeRequiredDefaultDescription
preparation_versionnumberno–Only for create_body from POST /invoices/prepare: version 1 binds the complete creation intent; unknown version → 409. Without this field the existing Create contract remains unchanged.
documentTextVersionnumberno–With preparation_version: required value 1; another text version → 409.
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–Must belong to the company
linesLineInput[]yes–At least one line item
invoiceType / invoice_typestring (Enum)noINVOICECREDIT_NOTE → 400, with a reference to POST /api/v1/credit-notesINVOICE | PROFORMA
issueDateISO datenotodayInvoice date
dueDateISO datenocustomer.paymentTermDays ?? company.paymentTermDays ?? 14 daysDue date
servicePeriodStart / servicePeriodEndISO date | nullno–Service period
currencystringnoEURCurrency code
reverseChargebooleannofalseVAT liability of the recipient
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.
taxExemptionReasonstring (Enum)no–Invalid → 400NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringno–Free text about the exemption
taxCountry / deliveryCountrystring (ISO-2)no–Tax or delivery country
ossApplicable / oss_applicablebooleanno–If omitted, OSS is derived from the tax context
ossCountry / oss_countrystring (ISO-2)no–OSS destination country
notesstringno–Internal note, not printed
footerstringno–Closing text (printed)
headerText / header_textstring (HTML)no–Opening text (printed)
customTitle / custom_titlestringno–Custom document title instead of Invoice
pdfWithoutLetterhead / pdf_without_letterheadbooleannofalsePDF without letterhead
invoiceDateIsServiceDate / invoice_date_is_service_datebooleannofalseInvoice date equals service date
useShippingAddress / use_shipping_addressbooleannofalseEnables shippingName/-Street/-ZipCode/-City/-Country
documentCategoryId / document_category_idstring | nullno–Document category
orderNumber / order_numberstringno–Purchase order number/order reference
buyerReference / buyer_referencestringno–Buyer reference or Leitweg-ID
eInvoiceAudit / e_invoiceobjectno–Audit data for format, submission channel, portal URL and status
metadataobjectno–Custom JSON object
lines[].descriptionstringno–Line item description
lines[].quantitynumberno1Quantity
lines[].unitPrice / unit_pricenumberno0Unit price in the document's price mode (net, or gross with pricesIncludeTax)
lines[].taxRate / tax_ratenumbernoStandard rate of the tax countryTax rate in %
lines[].discountnumberno0Absolute discount amount, not a percentage
lines[].unitstring | nullno–Processed only in a prepared body: binds the unit including the existing column default Stk. Ordinary Create bodies keep their existing behaviour.
lines[].lineType / line_typestring (Enum)noPRODUCTLine item typePRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Response: 201 { data: Invoice }, as in GET detail, without payments.

  • Creates a draft with an ENTWURF-… placeholder number. The actual number is assigned on transition to FINAL/SENT or POST …/send.
  • Use Idempotency-Key to retry safely after a timeout or connection loss. An invalid format returns 422 invalid_idempotency_key; if the invoice associated with the key has been deleted, the response is 409 idempotency_key_invoice_deleted. A replay does not check the document quota or emit a webhook. If the first request stops after creating the invoice, its INVOICE_CREATED webhook may be missing. An invalid Idempotency-Key is rejected rather than ignored.
  • Totals use prepareInvoiceTaxPayload, as in the dashboard: absolute line discounts, tax rates normalised to the tax country, and automatic OSS resolution if no flag is supplied.
  • Gross prices (pricesIncludeTax: true): VAT is extracted from the gross amount per tax rate, and the document total is the sum of the gross line amounts (3 × €19.99 = €59.97). lineTotal stays net, as do all exports and the e-invoice.
  • 400 for missing required fields, invalid enums or a discount exceeding the line amount (lineIndex in the response); 404 Customer/Company/Document category not found.
  • Audit INVOICE_CREATED_VIA_API. Webhook INVOICE_CREATED.
GET/api/v1/invoices/{id}— Read invoice details

Scope: invoices:read

Response: { data: Invoice } including footer, sentAt, paidAt, lockedAt, customer (with address/VAT ID), lines[], payments[] and paidAmount.

  • 404 Invoice not found, including for other companies.
PUT/api/v1/invoices/{id}— Update an invoice and/or change its status

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–Status change; invalid → 400 with allowedValuesDRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
documentCategoryId, dueDate, servicePeriodStart, servicePeriodEnd, reverseCharge, taxExemptionReason, taxExemptionNote, taxCountry, deliveryCountry, ossApplicable, ossCountry, headerText, notes, footer, orderNumber, buyerReference, customTitle, pdfWithoutLetterhead, invoiceDateIsServiceDate, useShippingAddress + shipping*, eInvoiceAudit/e_invoicemixedno–All optional, also accepted as snake_case; content fields only. See locking notes
pricesIncludeTax / prices_include_taxbooleanno–Changes the price mode: VAT and totals are recalculated from the prices; the prices themselves stay unchanged. Without a value the stored price mode is kept. Only true/false, otherwise 400.
linesLineInput[]no–Replaces all line items (at least one)

Response: 200 { data: { id, invoiceNumber, status, netTotal, taxTotal, grossTotal, pricesIncludeTax, orderNumber, buyerReference, e_invoice, updatedAt, [stornoInvoiceId, stornoInvoiceNumber] } }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403 plan_limit_reached (cancelling a draft remains possible).
  • Status transitions use lib/invoice-status-transitions.ts: DRAFT→FINAL|SENT|CANCELLED, FINAL→SENT|DRAFT|CANCELLED, SENT→PAID|OVERDUE|CANCELLED, OVERDUE→PAID|CANCELLED; PAID/CANCELLED are final states. Invalid → 400 with allowedTransitions.
  • Credit notes cannot be set to OVERDUE: 400 with code credit_note_overdue, even when a historical document is already OVERDUE. allowedTransitions accounts for the document type; invoices and unconverted proformas are unchanged.
  • DRAFT→FINAL/SENT assigns the actual number atomically from the document type's number range without gaps; →SENT sets sentAt and locks the document (lockedAt, v1 snapshot); FINAL deliberately remains unlocked; →PAID sets paidAt.
  • →CANCELLED automatically creates a cancellation credit note for issued invoices, as with POST …/cancel and createStorno: true, without an email.
  • Content can only change on editable invoices (DRAFT or FINAL and not locked, lib/invoice-lock.ts); otherwise 400 with lockedFields and a reference to the correction endpoint. An unchanged read-modify-write body does not prevent a status transition.
  • Webhooks INVOICE_SENT/INVOICE_PAID/INVOICE_CANCELLED on status changes, otherwise INVOICE_UPDATED; also CREDIT_NOTE_CREATED for automatic cancellation credit notes. Audit INVOICE_UPDATED_VIA_API. Conflicts → 409.
DELETE/api/v1/invoices/{id}— Delete an invoice draft

Scope: invoices:write

Response: 200 { success: true }

  • Drafts only (DRAFT), otherwise 400. Deletes the line items and document in one transaction and releases linked source documents: quote, order confirmation or delivery note.
  • A draft that already has an issued number (for example after a failed email) returns 409 { code: "invoice_number_issued", invoiceNumber }. To preserve the numbering sequence, resend it or cancel it by setting status CANCELLED (without a cancellation credit note).
  • Audit INVOICE_DELETED_VIA_API.
GET/api/v1/invoices/{id}/pdf— Download an invoice PDF

Scope: invoices:read

Response: 200 PDF binary, Content-Type application/pdf, Content-Disposition inline, header X-PDF-Source: generated|s3-cache.

  • Renders through lib/invoice-pdf-bundle.ts using the dashboard layout, deliberately without the S3 cache.
  • 404 Invoice not found. Audit PDF_DOWNLOADED_VIA_API only when found.
GET/api/v1/invoices/send-capability— Check opt-in send capability

Scope: invoices:write

Response: 200 { data: InvoiceSendCapability }

  • Authenticated and uncached. supported=false when the feature is disabled, schema/company gate is missing, or recovery epoch differs. No test email.
GET/api/v1/invoices/{id}/send-status— Read historical opt-in send status

Scope: invoices:write

HTTP headers

FieldTypeRequiredDefaultDescription
Idempotency-Keystringyes–Original unchanged send key; never use a URL parameter.

Response: 200 { data: InvoiceSendStatus }

  • Only reads existing state: 202 pending/unconfirmed, 409 requires review or confirmed not submitted; 404 without a receipt is not evidence of non-acceptance. Stored states remain readable after POST expiry and while sending is disabled. API authentication/usage logging remains in place.
  • resolution_decision contains only the explicit review outcome (or null), without operator or evidence references. UNKNOWN remains the historical state; CONFIRMED_ACCEPTED confirms acceptance, not delivery.
POST/api/v1/invoices/{id}/send— Send an invoice by email

Scope: invoices:write

HTTP headers

FieldTypeRequiredDefaultDescription
Idempotency-Keystringno–Opt-in invoice_send_v1; returns 503 without an active capability, never falls back to legacy delivery.

Body fields

FieldTypeRequiredDefaultDescription
recipientEmail / recipient_emailstringnoCustomer's email addressRecipient
ccstringno–Copy
bccstringno–Blind copy

Response: 200 { data: { invoiceId, invoiceNumber, status (lowercase), sentTo, cc, bcc, sentAt } } (also available as snake_case)

  • Opt-in proposal #719, disabled by default: first check GET /api/v1/invoices/send-capability with invoices:write. Only supported=true enables the new contract; OpenAPI alone is not evidence of activation.
  • With key cb-send-v1.<13-digit Unix milliseconds>.<lowercase UUID-v4>: recipient_email and expected_updated_at (UTC ISO with milliseconds) are required; cc/bcc are arrays of bare ASCII mailboxes. Without a key, the existing string-CC/BCC body and customer fallback remain unchanged.
  • Opt-in: 24h until first admission AND first transport, 30 days historical replay, 5min future tolerance; fixed deadlines from key time. 202 means an existing attempt, 200 ACCEPTED only provider acceptance, 409 UNKNOWN/partial acceptance requires review, 410 expired, 422 invalid key/body. Never automatically replace the key or fall back to no key.
  • Sending a draft with an exhausted document quota returns 403 plan_limit_reached before a number is allocated.
  • Business logic: lib/invoice-api-email.ts. Drafts with a placeholder receive an issued number before sending (counter, invoice and INVOICE_NUMBER_ISSUED audit in one transaction). If delivery fails, the number stays on the draft and is reused on the next attempt; it is never returned to the sequence. PDF and email content match the dashboard.
  • Only after successful delivery: status DRAFT/FINAL → SENT, sentAt, document lock (lockedAt, v1). Audit INVOICE_SENT_VIA_API, webhook INVOICE_SENT.
  • A cancelled invoice can be emailed and remains cancelled. Records sentAt if absent, an audit entry and webhook INVOICE_SENT with the actual status.
  • A draft or final invoice is reserved while it is being sent, as in the dashboard. A concurrent second send of the same invoice (API, individual or bulk send) receives 409 send_in_progress without sending email or assigning a number. After a crash, the reservation expires in ten minutes.
  • Errors: 404 unknown invoice; 400 no recipient or unissued draft with a placeholder number; 409 converted proforma or send already in progress (send_in_progress); 500 delivery failed.
  • 409 converted proforma: { error, invoice_id, invoice_number } identifies the invoice to send. invoiceId/invoiceNumber (the same values) are deprecated and will be removed in a later version.
POST/api/v1/invoices/{id}/cancel— Cancel an invoice, optionally creating a cancellation credit note

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
createStorno / create_stornobooleannotrueCreate a cancellation credit note
sendStornoToCustomer / send_storno_to_customerbooleannofalseEmail the cancellation credit note
recipientEmail / recipient_emailstringno–Only relevant when sending

Response: 200 { data: { id, invoiceNumber, status: "CANCELLED", stornoInvoiceId, stornoInvoiceNumber, stornoEmailSent, [warning] } }

  • Uses cancelInvoiceCore (lib/invoices/cancel.ts, shared with the dashboard and the AI assistant; the write is cancelInvoiceWithOptionalStorno in lib/storno.ts). A corresponding credit note is created only for issued INVOICE documents (isStornoEligible): reason CANCELLATION, its own GS number, status FINAL and negative amounts, atomically with the status change.
  • Drafts, proformas and credit notes are only set to CANCELLED. Cancellation is allowed from DRAFT, FINAL, SENT or OVERDUE; otherwise 409. Concurrent status change → 409.
  • Payments transferred from a proforma are returned to that proforma on cancellation. If the proforma is missing or cancelled (legacy data), nothing is written: 409 instructs you to remove the payments first, as with PUT status CANCELLED.
  • Optional email delivery is non-fatal (→ warning); cancellation remains effective. Webhooks INVOICE_CANCELLED and CREDIT_NOTE_CREATED, plus INVOICE_SENT on delivery.
  • Audit INVOICE_CANCELLED_VIA_API (actor: the company's owner; with several owners, the one with the oldest membership).
  • 409 converted proforma: { error, invoice_id, invoice_number } identifies the invoice to cancel. invoiceId/invoiceNumber (the same values) are deprecated and will be removed in a later version.
POST/api/v1/invoices/{id}/storno— Create a cancellation credit note for an already cancelled invoice

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
sendToCustomer / send_to_customerbooleannofalseSend the cancellation credit note
recipientEmail / recipient_emailstringno–Recipient

Response: 201 { data: { id, invoiceNumber, invoiceType: "CREDIT_NOTE", creditNoteReason: "CANCELLATION", status: "FINAL", parentInvoiceId, issueDate, currency, netTotal, taxTotal, grossTotal, stornoEmailSent, [warning] } }

  • Matches createRetroactiveStorno for invoices already CANCELLED but without a cancellation credit note. No status change.
  • 404 unknown invoice; 409 invoice not CANCELLED (reference to …/cancel) or a cancellation credit note already exists; 400 ineligible document, such as a proforma or draft.
  • Webhook CREDIT_NOTE_CREATED, plus INVOICE_SENT on delivery. Audit INVOICE_STORNO_CREATED_VIA_API.
POST/api/v1/invoices/{id}/duplicate— Duplicate an invoice as a new draft

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
customerId / customer_idstringno–A different customer from the original
adjustDates / adjust_datesbooleannotrueInvoice date becomes today; the payment term in days stays the same

Response: 201 { data: { id, invoiceNumber, invoiceType: "INVOICE", status: "DRAFT", sourceInvoiceId, customerId, documentCategoryId, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, createdAt } }

  • Uses lib/invoice-duplicate.ts. The copy is always a regular invoice draft with a placeholder number. Quantities and totals are copied as positive values, including when copying a credit note. The service period is not copied.
  • 404 Invoice/Customer not found; 403 plan_limit_reached when the plan's document quota is reached (the copy counts as a new document). Audit INVOICE_DUPLICATED_VIA_API. No webhook, matching the dashboard.
POST/api/v1/invoices/{id}/convert— Convert a proforma to a regular invoice

Scope: invoices:write

Response: 201 { data: { id, invoiceNumber, invoiceType: "INVOICE", status: "DRAFT", proformaInvoiceId, proformaInvoiceNumber, customerId, documentCategoryId, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, createdAt } }

  • No body. Uses convertProformaCore (lib/invoices/proforma.ts, shared with the dashboard and the AI assistant; the write is in lib/proforma-conversion.ts). The proforma keeps its number, document type and status, and is linked through metadata.convertedToInvoiceId, with metadata.convertedFromProformaId on the invoice.
  • Opening and closing text come from the company's invoice templates, not the proforma. Conversion is allowed from DRAFT, FINAL, SENT or OVERDUE.
  • 404 unknown document; 400 not a proforma; 403 plan_limit_reached at the document quota; 409 already converted (identifies the invoice) or status no longer convertible.
  • Audit CONVERT_TO_INVOICE on the proforma and CREATE_FROM_PROFORMA on the invoice. Webhook INVOICE_CREATED.
GET/api/v1/invoices/{id}/payments— List an invoice's payments

Scope: invoices:read

Response: { data: { invoice_id, invoice_number, gross_total, total_paid, amount_due, currency, payments: [{ id, amount, payment_date/paymentDate, payment_method/paymentMethod, reference, notes, created_at/createdAt }] } }, payments sorted by date descending.

  • 404 Invoice not found for an unknown invoice or one from another company.
POST/api/v1/invoices/{id}/payments— Record an invoice payment

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
amountnumberyes–Amount, must be > 0
payment_method / paymentMethodstring (Enum)noBANK_TRANSFERCase and hyphens are ignoredBANK_TRANSFER | CASH | CREDIT_CARD | PAYPAL | OTHER
payment_date / paymentDateISO datenonowPayment date
referencestringno–For example, a transaction ID
notesstringno–Free text

Response: 201 { data: { …payment, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus (lowercase), total_paid/totalPaid, amount_due/amountDue } }

  • When paid in full, the invoice becomes PAID with paidAt set to the payment date and webhook INVOICE_PAID is triggered. Audit PAYMENT_RECORDED_VIA_API.
  • 400 amount missing/≤0; 400 invalid payment_method (with allowedValues); 400 invalid payment_date; 400 (code invoice_status) unless the invoice is FINAL/SENT/OVERDUE; 409 (code amount_exceeds_remaining) above the outstanding balance + €0.01; 404 unknown invoice or another company's invoice.
PUT/api/v1/invoices/{id}/payments/{paymentId}— Update a payment

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
amountnumberno–> 0, default is the previous amount
payment_method / paymentMethodstring (Enum)noprevious payment methodAs for POSTBANK_TRANSFER | CASH | CREDIT_CARD | PAYPAL | OTHER
payment_date / paymentDateISO datenoprevious date
referencestring | nullno–
notesstring | nullno–

Response: 200 { data: { …payment, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus, total_paid/totalPaid, amount_due/amountDue } }

  • Status update: paid in full → PAID + paidAt + webhook INVOICE_PAID; outstanding again → SENT, paidAt cleared. Audit PAYMENT_UPDATED_VIA_API.
  • 404 Payment not found, including for another invoice/company; 400 amount ≤0, invalid payment method or date; 409 (code invoice_cancelled) for a cancelled invoice; 409 (code amount_exceeds_remaining) above the balance excluding this payment.
DELETE/api/v1/invoices/{id}/payments/{paymentId}— Delete a payment

Scope: invoices:write

Response: 200 { data: { id, deleted: true, invoice_id/invoiceId, invoice_number/invoiceNumber, invoice_status/invoiceStatus, total_paid/totalPaid, amount_due/amountDue } }

  • If the invoice was PAID and has a balance again after deletion, it returns to SENT and paidAt is cleared. Deliberately allowed on cancelled invoices to remove incorrect postings.
  • Audit PAYMENT_DELETED_VIA_API. 404 Payment not found.
GET/api/v1/invoices/{id}/dunning— Read reminder status and history

Scope: invoices:read

Response: { data: { invoice_id, invoice_number, status, due_date, days_overdue, gross_total, customer, dunning: { is_paused, paused_at, paused_reason, current_level, next_level/nextLevel, max_level_reached, total_reminders, total_fees, total_interest, total_outstanding }, reminders: [...] } }

  • next_level/nextLevel/max_level_reached are new; next_level is the stage sent next by action: "send" (stage 3 stays at stage 3).
POST/api/v1/invoices/{id}/dunning— Pause or resume reminders, or send a reminder stage

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
actionstring (Enum)yes–pause | resume | sendpause | resume | send
reasonstringno–Stored only for pause
recipient_email / recipientEmailstringnoCustomer's email addressOnly for send
custom_reminder_fee / customReminderFeenumbernoCompany.reminderFee1/2/3 by stageOnly for send, ≥ 0
include_interest / includeInterestbooleannofalseOnly for send; rate from Company.defaultInterestRate, simple interest: outstanding amount × rate × days/365

Response: pause/resume: 200 { data: { invoice_id, invoice_number, dunning_paused, dunning_paused_at, dunning_paused_reason } }. send: 201 { data: { id, invoice_id/invoiceId, level, sent_at/sentAt, sent_to/sentTo, fee, interest_rate/interestRate, interest_amount/interestAmount, total_amount/totalAmount, days_overdue/daysOverdue, remaining_amount/remainingAmount } }

  • pause/resume: sets dunningPaused/-At/-Reason, audit DUNNING_PAUSED_VIA_API / DUNNING_RESUMED_VIA_API.
  • send: sends the branded reminder email (stage 1: payment reminder, 2: first formal reminder, 3: final reminder), creates a Reminder row, changes SENT → OVERDUE (webhook INVOICE_OVERDUE), and triggers REMINDER_SENT plus REMINDER_ESCALATED from stage 2. Audit REMINDER_SENT_VIA_API.
  • 400 invalid action/field types; 400 (code invoice_status) unless SENT/OVERDUE; 400 (code no_recipient) without a customer email; 409 dunning_paused/max_level_reached/already_paid; 502 (code email_failed) on failed delivery, with no Reminder row.
  • send is blocked for credit notes: 400 with code credit_note_dunning before sending, creating a Reminder row or changing status, regardless of amount or historical OVERDUE status. Reading reminder history and pause/resume are unchanged.
POST/api/v1/invoices/{id}/correct— Create a correction under § 31 Abs. 5 UStDV as a new version

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
change_reason / changeReasonstringyes–At least MIN_CHANGE_REASON_LENGTH characters
customer_id / customerIdstringno–Change customer
issue_date, due_date, service_period_start, service_period_endISO dateno–
reverse_chargebooleanno–
tax_exemption_reasonstring (Enum)no–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
tax_exemption_note, tax_country, delivery_country, oss_countrystringno–
oss_applicablebooleanno–
header_text, notes, footer, order_number, buyer_referencestringno–
linesLineInput[]no–Replaces all line items; each item accepts description (required), quantity (default 1), unit_price (default 0), tax_rate (default 0), discount (absolute, default 0), line_type (default PRODUCT)PRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK

Response: 200 { data: { invoiceId, invoiceNumber, versionNumber, changeReason, lazyInitialVersion } }

  • Keeps the invoice number and creates a DocumentVersion (CORRECTION) with a full snapshot. Recalculates taxes and totals, regenerates and archives the PDF. For legacy invoices without lockedAt, v1 is created retrospectively (lazyInitialVersion: true).
  • Audit DOCUMENT_CORRECTED, webhook INVOICE_UPDATED. 400 missing/short change_reason; 400 (code not_locked), use PUT instead; 400 invalid enum/date/number or empty lines; 404 unknown invoice/customer or another company's record.
GET/api/v1/invoices/{id}/versions— Read an invoice's version history

Scope: invoices:read

Response: { data: { invoiceId, currentVersion, versions: [{ id, versionNumber, changeType, changeReason, hasPdf, createdAt, createdBy }] } }, sorted by versionNumber descending.

  • Same fields as dashboard route /api/documents/invoice/{id}/versions. 404 Invoice not found.
GET/api/v1/invoices/{id}/versions/{version}/pdf— Download the archived PDF of a specific version

Scope: invoices:read

Query parameters

FieldTypeRequiredDefaultDescription
versionnumber (path parameter)yes–Version number ≥ 1

Response: 200 PDF bytes, Content-Disposition inline; filename="{document number}-v{n}.pdf", Cache-Control private, max-age=3600, immutable.

  • Returns only the archived PDF, never a newly rendered file (GoBD). Audit DOCUMENT_VERSION_PDF_DOWNLOADED.
  • 400 Invalid version number; 404 Invoice/Version not found or the version's PDF is unavailable or missing from storage.
GET/api/v1/invoices/{id}/facturx— Download Factur-X/ZUGFeRD XML

Scope: invoices:read

Response: 200 XML, Content-Type application/xml; charset=utf-8, Content-Disposition attachment.

  • Factur-X/ZUGFeRD 2.3 (EN 16931, CII, BASIC profile), matching the dashboard download. Drafts, credit notes (TypeCode 381) and proformas (325) return XML; proformas already converted to invoices return 409 with a reference to the invoice.
  • Internal notes are excluded; tax notices and closing text are included. Audit EINVOICE_XML_DOWNLOADED_VIA_API. 404 Invoice not found.
Credit notes6 endpoints · invoices:read, invoices:write

Standalone credit notes, credit notes linked to an invoice, and their payouts. Credit notes are Invoice rows and share invoices:read/invoices:write scopes.

MethodPathScopeSummary
GET/api/v1/credit-notesinvoices:readList credit notes
POST/api/v1/credit-notesinvoices:writeCreate a standalone credit note or one linked to an invoice
GET/api/v1/credit-notes/{id}invoices:readRead credit note details
PUT/api/v1/credit-notes/{id}invoices:writeUpdate a credit note draft
POST/api/v1/credit-notes/{id}/executeinvoices:writeExecute a payout (credit note → PAID)
PUT/api/v1/credit-notes/{id}/executeinvoices:writeApprove, cancel or mark a payout as failed
GET/api/v1/credit-notes— List credit notes

Scope: invoices:read

Query parameters

FieldTypeRequiredDefaultDescription
limitnumberno50Page size
offsetnumberno0Offset
recipient_id / customer_idstringno–Filter by recipient
statusstring (Enum InvoiceStatus)no–DRAFT | FINAL | SENT | PAID | OVERDUE | CANCELLED
payout_statusstring (Enum)no–Filters in the query (payout.is.status)PENDING | APPROVED | EXECUTED | FAILED | CANCELLED
category_idstring | "uncategorized"no–

Response: { data: CreditNoteListItem[], pagination: { total, limit, offset, hasMore, has_more } }

  • payout_status is filtered in the database query rather than after pagination, so total/has_more match the result.
  • Invalid status/payout_status → 400 with allowedValues, previously Prisma returned 500. Sorted by issueDate descending.
POST/api/v1/credit-notes— Create a standalone credit note or one linked to an invoice

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
recipient_id / recipientIdstringno–Required unless parent_invoice_id is set
reasonstring (Enum)noPAYOUTCANCELLATION is not allowed (→ 400)PAYOUT | COMMISSION | GOODWILL | RETURN | PRICE_CORRECTION | OTHER
linesLineInput[]no–Required except in linked mode (parent_invoice_id without lines)
parent_invoice_id / parentInvoiceIdstringno–Linked mode
partial_lines / partialLinesArray<{line_id/lineId, quantity}>no–Only in linked mode without lines; otherwise all line items are credited
issue_date / issueDateISO datenotoday
currencystringnoCurrency of the source invoice, or EUR
reverse_charge / reverseChargebooleanno–
tax_exemption_reason / taxExemptionReasonstring (Enum)no–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
prices_include_tax / pricesIncludeTaxbooleannofalseOnly with own lines: true = unit prices include VAT, false = net; without a value net. A credit note for an invoice (parent_invoice_id without lines) takes that invoice's price mode; a value there → 400.
notesstringno–Stored unchanged; no text is generated from the reason
footerstring | nullno–Missing/null → notes is also used as closing text; an empty string deliberately leaves it blank
metadataobjectno–
create_payout / createPayoutbooleannofalse
payout_iban, payout_bic, payout_account_holder, payout_bank_name, payout_referencestringno–No IBAN in either body or customer → 400

Response: 201 { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, issue_date, recipient, currency, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, lines[], notes, footer, metadata, parent_invoice_id, payout, created_at } }

  • New credit notes are always drafts with an ENTWURF-… placeholder number. The actual GS number is assigned on issue: PUT status change, POST …/send or POST /credit-notes/{id}/execute.
  • Linked mode (parent_invoice_id without lines) matches createCreditNote: only for SENT/PAID/OVERDUE invoices, otherwise 409. Tax details and document category come from the source invoice.
  • Without reverse_charge and tax_exemption_reason, the tax treatment of the source invoice (parent_invoice_id) applies, otherwise the recipient's default (defaultTaxExemptionReason including defaultTaxExemptionNote), otherwise NONE.
  • Amounts and quantities are stored as negative values, matching the dashboard; payout.amount is positive.
  • 404 missing source invoice/recipient or another company's record. Audit CREDIT_NOTE_CREATED_VIA_API, webhook CREDIT_NOTE_CREATED.
GET/api/v1/credit-notes/{id}— Read credit note details

Scope: invoices:read

Response: { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, issue_date, due_date, recipient (with bank details), currency, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, reverse_charge, tax_exemption_reason, lines[], notes, footer, metadata, parent_invoice, payout, created_at, updated_at } }

  • 404 for a missing credit note or one from another company.
PUT/api/v1/credit-notes/{id}— Update a credit note draft

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
notesstringno–
footerstring | nullno–
metadataobjectno–
reasonstring (Enum)no–Excludes CANCELLATIONPAYOUT | COMMISSION | GOODWILL | RETURN | PRICE_CORRECTION | OTHER
issue_date / issueDateISO dateno–
currencystringno–
reverse_charge / reverseChargebooleanno–
tax_exemption_reason / taxExemptionReasonstring (Enum)no–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
linesLineInput[]no–Replaces line items; totals are recalculated through calculateDocumentTotals as negative values
prices_include_tax / pricesIncludeTaxbooleanno–Only together with lines (otherwise 400): price mode of the new lines. Without a value the stored price mode is kept.

Response: { data: { id, invoice_number/invoiceNumber, numberIssued, credit_note_reason/creditNoteReason, status, currency, issue_date, net_total, tax_total, gross_total, prices_include_tax/pricesIncludeTax, lines[], notes, footer, metadata, updated_at } }

  • DRAFT only, otherwise 400. Line replacement and totals run in one transaction.
  • Audit CREDIT_NOTE_UPDATED_VIA_API.
POST/api/v1/credit-notes/{id}/execute— Execute a payout (credit note → PAID)

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
transaction_id / transactionIdstringno–
executed_at / executedAtISO datenonow
notesstringno–Appended to payout.description

Response: 200 { data: { id, credit_note_id, credit_note_number, status, amount, currency, reference, iban, bic, transaction_id, executed_at, credit_note_status } }

  • Sets the payout to EXECUTED and the credit note to PAID. If the credit note still has a placeholder number, the actual GS number is assigned in the transaction; a placeholder payout.reference is replaced with the GS number.
  • A draft is issued by this call and then counts towards the document quota: if the quota is used up, 403 { error, code: "plan_limit_reached" } — no number is drawn and nothing is booked (#696). Credit notes that are already issued are not affected.
  • 400 no payout/already executed/cancelled; 409 concurrent issue. Audit PAYOUT_EXECUTED_VIA_API, webhooks PAYOUT_EXECUTED + CREDIT_NOTE_PAID. Uses executeCreditNoteCore (lib/credit-notes.ts).
PUT/api/v1/credit-notes/{id}/execute— Approve, cancel or mark a payout as failed

Scope: invoices:write

Body fields

FieldTypeRequiredDefaultDescription
actionstring (Enum)yes–approve only from PENDING; fail only from APPROVED; cancel not from EXECUTEDapprove | cancel | fail
failure_reason / failureReasonstringno–
approved_by / approvedBystringno"API"

Response: { data: { id, credit_note_id, status, amount, approved_at, approved_by, failure_reason } }

  • cancel sets the credit note to CANCELLED; a draft deliberately receives no document number.
  • Audit PAYOUT_APPROVE|CANCEL|FAIL_VIA_API, Webhooks PAYOUT_APPROVED / PAYOUT_CANCELLED / PAYOUT_FAILED.
Customers10 endpoints · customers:read, customers:write

Customer details including addresses, bank details, SEPA mandate, VAT validation through VIES and duplicate search.

MethodPathScopeSummary
GET/api/v1/customerscustomers:readList customers
POST/api/v1/customerscustomers:writeCreate a customer
GET/api/v1/customers/{id}customers:readRead customer details
PUT/api/v1/customers/{id}customers:writeUpdate a customer
DELETE/api/v1/customers/{id}customers:writeDelete a customer
POST/api/v1/customers/{id}/archivecustomers:writeArchive a customer
POST/api/v1/customers/{id}/unarchivecustomers:writeRestore a customer from the archive
POST/api/v1/customers/{id}/validate-vatcustomers:writeValidate a VAT ID through VIES and save the result on the customer
GET/api/v1/customers/duplicatescustomers:readFind similar customers by name
GET/api/v1/customers/by-email/{email}customers:readFind a customer by email address
GET/api/v1/customers— List customers

Scope: customers:read

Query parameters

FieldTypeRequiredDefaultDescription
limitnumberno501–100
offsetnumberno0
searchstringno–Case-insensitive match on name, email or customerNumber
include_archived / includeArchivedboolean (true|1|yes)no–Include archived customers
archivedbooleanno–true = archived only, false = active only

Response: { data: Customer[], pagination }

  • Archived customers are excluded unless include_archived/archived is set, matching the dashboard customer list. Sorted by name ascending.
POST/api/v1/customers— Create a customer

Scope: customers:write

Body fields

FieldTypeRequiredDefaultDescription
namestringyes–Not empty
customerNumberstringno–Empty/missing = automatic allocation (lib/customer-number.ts)
salutation, title, firstName, lastName, departmentstringno–
email, phone, mobile, websitestringno–
taxIdstringno–
taxNumber, registryCourt, registryNumberstringno–
bmdAccountNumber, bmdRevenueAccountstringno–Digits only, at most nine
datevIdstringno–
documentLocalestring | nullno–Language for new documents; null inherits the company setting. document_locale is also accepted. Existing documents and recurring schedules remain unchanged.de | en
defaultTaxExemptionReasonstring (Enum) | nullno–NONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
defaultTaxExemptionNotestringno–
street, zipCode, city, state, countryCodestringno–Billing address
countrystringnoÖsterreichAn empty value makes no change
shippingName, shippingCompany, shippingStreet, shippingZipCode, shippingCity, shippingState, shippingCountry, shippingCountryCodestringno–Delivery address
bankAccountHolder, bankName, iban, bicstringno–
sepaMandateReferencestringno–
sepaMandateDateISO dateno–
sepaMandateTypestring (Enum)no–CORE | B2B
sepaMandateStatusstring (Enum)no–ACTIVE | REVOKED | EXPIRED
sepaSequenceTypestring (Enum)no–FRST | RCUR | OOFF | FNAL
paymentTermDaysnumberno–≥ 0
discountPercentnumberno–0–100
discountDaysnumberno–≥ 0
notes, categorystringno–
contacts, billingPrefs, metadataobject | arrayno–null clears the field
address, shippingAddressstringno–Free text; derived from structured fields if any are supplied

Response: 201 { data: Customer }

  • Plan gate checkCustomerLimit → 403 { code: "plan_limit_reached", limit, current }.
  • Duplicate email returns 409 { customerId } identifying the oldest existing customer, including archived customers. The entire address is compared case-insensitively; _ and % are literal characters. Concurrent POST requests for the same address also create exactly one customer. An occupied customerNumber returns 409 { code: "CUSTOMER_NUMBER_TAKEN" }; an exhausted number range returns 409 { code: "CUSTOMER_NUMBER_UNAVAILABLE" }.
  • taxIdValidated is never accepted from input. It is set only if the same company successfully validated the same VAT ID through VIES within the last hour.
  • Audit CUSTOMER_CREATED_VIA_API, Webhook CUSTOMER_CREATED.
GET/api/v1/customers/{id}— Read customer details

Scope: customers:read

Response: { data: Customer & { invoiceCount, recentInvoices: [...] } } (ten most recent documents)

  • 404 for a missing customer or one from another company.
PUT/api/v1/customers/{id}— Update a customer

Scope: customers:write

Body fields

FieldTypeRequiredDefaultDescription
(alle Felder von POST)mixedno–All optional, with PATCH semantics: only supplied fields are written. customerNumber: ""/null removes the number without allocating a new one.

Response: { data: Customer }

  • Behaviour change: the route previously wrote only six fields (name, email, taxId, address, shippingAddress, contacts) and discarded the rest. It now supports the full form.
  • Changing an email to one already used by another customer (case-insensitive) returns 409 { customerId }, checked under the same lock as customer creation. An occupied customer number returns 409 { code: "CUSTOMER_NUMBER_TAKEN" }. Changing taxId resets taxIdValidated, or adopts a VIES check no more than one hour old.
  • Audit CUSTOMER_UPDATED_VIA_API, Webhook CUSTOMER_UPDATED.
DELETE/api/v1/customers/{id}— Delete a customer

Scope: customers:write

Response: { success: true }

  • Unused customers only (lib/customer-lifecycle.ts). Any reference → 409 { code: "CUSTOMER_IN_USE" }; archiving is recommended instead.
  • Webhook CUSTOMER_DELETED.
POST/api/v1/customers/{id}/archive— Archive a customer

Scope: customers:write

Response: 200 { data: Customer }

  • Body is ignored. Sets isArchived=true and archivedAt=now. Audit CUSTOMER_ARCHIVED_VIA_API, webhook CUSTOMER_UPDATED. 404 for another company's customer.
POST/api/v1/customers/{id}/unarchive— Restore a customer from the archive

Scope: customers:write

Response: 200 { data: Customer }

  • Body is ignored. Sets isArchived=false and archivedAt=null. Audit CUSTOMER_UNARCHIVED_VIA_API, webhook CUSTOMER_UPDATED.
POST/api/v1/customers/{id}/validate-vat— Validate a VAT ID through VIES and save the result on the customer

Scope: customers:write

Body fields

FieldTypeRequiredDefaultDescription
vatNumber / vat_numberstringno–
taxId / tax_idstringno–If both are omitted, checks the stored VAT ID

Response: 200 { data: { valid, unavailable, countryCode, vatNumber, requestDate, name, address, errorMessage, customer: Customer } }

  • Calls VIES (lib/vies.ts), writes a VatValidation row and saves the normalised taxId, taxIdValidated and taxIdValidatedAt on the customer.
  • No VAT ID → 400. Audit CUSTOMER_VAT_VALIDATED_VIA_API, webhook CUSTOMER_UPDATED. The result can be used for a subsequent POST/PUT with the same VAT ID for one hour.
  • unavailable=true means VIES could not be reached because of timeout, maintenance or network failure. In that case, valid=false says nothing about the VAT ID. The customer's stored result remains unchanged if it belongs to the checked VAT ID.
GET/api/v1/customers/duplicates— Find similar customers by name

Scope: customers:read

Query parameters

FieldTypeRequiredDefaultDescription
namestringyes–At most 200 characters; fewer than three returns {data:[]}
exclude_id / excludeIdstringno–

Response: { data: [{ id, name, customerNumber, city, isArchived, similarity }] } (at most five, sorted by similarity descending)

  • Fuzzy comparison ≥ 0.65 (lib/customer-duplicates.ts), including archived customers. Read-only query.
GET/api/v1/customers/by-email/{email}— Find a customer by email address

Scope: customers:read

Response: { data: Customer & { invoiceCount } }

  • Matches the whole address case-insensitively; _ and % are literal characters, not wildcards. Returns 404 when no customer matches. If several customers share the address, returns the oldest, as in the POST /customers 409 response. Archived customers remain searchable.
Products5 endpoints · products:read, products:write

Product and service catalogue for pre-filling line items.

MethodPathScopeSummary
GET/api/v1/productsproducts:readList products
POST/api/v1/productsproducts:writeCreate a product
GET/api/v1/products/{id}products:readRead product details
PUT/api/v1/products/{id}products:writeUpdate a product
DELETE/api/v1/products/{id}products:writeDeactivate a product (soft delete)
GET/api/v1/products— List products

Scope: products:read

Query parameters

FieldTypeRequiredDefaultDescription
searchstringno–Case-insensitive match on name/sku
isService / is_serviceboolean ("true"|"false")no–
include_inactiveboolean ("true"|"false")notrueDeliberate compatibility choice: defaults to true so existing integrations still see all products; the route previously never filtered by isActive
limitnumberno50
offsetnumberno0

Response: { data: Product[], pagination }

  • No plan gate.
  • include_inactive=false opts into active products only.
POST/api/v1/products— Create a product

Scope: products:write

Body fields

FieldTypeRequiredDefaultDescription
namestringyes–
descriptionstringno–
skustringno–Unique within the company → 409 if already taken
isService / is_servicebooleannofalse
pricenumberyes–Must be ≥ 0
taxRate / tax_ratenumberno20Must be 0–100
pricesIncludeTax / prices_include_taxbooleannofalsetrue = price is a gross price including VAT, false = net. Without a value net — even if the company defaults to gross prices. Only true/false, otherwise 400.
unitstringno"Stück"
isActive / is_activebooleannotrue

Response: 201 { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • Audit PRODUCT_CREATED_VIA_API. The response now also includes updatedAt.
GET/api/v1/products/{id}— Read product details

Scope: products:read

Response: { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • 404 if not found. Inactive products remain readable by ID.
PUT/api/v1/products/{id}— Update a product

Scope: products:write

Body fields

FieldTypeRequiredDefaultDescription
(alle Felder von POST)mixedno–All optional/partial, with snake_case aliases through pickField. price/taxRate are validated as for POST.

Response: 200 { data: { id, name, description, sku, isService, price, taxRate, pricesIncludeTax, unit, isActive, createdAt, updatedAt } }

  • 404 if not found; 409 on an SKU conflict with another product. Audit PRODUCT_UPDATED_VIA_API. The response now also includes createdAt.
  • pricesIncludeTax only changes the price mode; price is not converted. Without a value the stored price mode is kept.
DELETE/api/v1/products/{id}— Deactivate a product (soft delete)

Scope: products:write

Response: 200 { success: true }

  • Sets isActive: false and keeps the row. Audit PRODUCT_DEACTIVATED_VIA_API. 404 if not found.
Quotes9 endpoints · quotes:read, quotes:write

Quotes, including delivery, status changes and conversion to an invoice or order confirmation.

MethodPathScopeSummary
GET/api/v1/quotesquotes:readList quotes
POST/api/v1/quotesquotes:writeCreate a quote
GET/api/v1/quotes/{id}quotes:readRead quote details
PUT/api/v1/quotes/{id}quotes:writeUpdate a quote draft
DELETE/api/v1/quotes/{id}quotes:writeDelete a quote draft
POST/api/v1/quotes/{id}/statusquotes:writeAccept or reject a quote
POST/api/v1/quotes/{id}/sendquotes:writeSend a quote by email
GET/api/v1/quotes/{id}/pdfquotes:readDownload a quote PDF
POST/api/v1/quotes/{id}/convertquotes:write, invoices:writeConvert a quote to an invoice or order confirmation
GET/api/v1/quotes— List quotes

Scope: quotes:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–Filter by stored statusDRAFT | SENT | ACCEPTED | REJECTED | EXPIRED | CONVERTED
customer_id / customerIdstringno–
searchstringno–Case-insensitive match on quote number and customer name
from, toISO dateno–Range over issueDate
category_idstring | "uncategorized"no–
limitnumberno50
offsetnumberno0

Response: { data: Quote[], pagination }

  • Sorted by issueDate descending. EXPIRED is never stored in the database; it appears only in displayStatus.
POST/api/v1/quotes— Create a quote

Scope: quotes:write

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–
validUntilISO dateyes–
issueDateISO datenonow
servicePeriodStart, servicePeriodEndISO date | nullno–
documentCategoryIdstring | nullno–
reverseChargebooleannofalse
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.
headerTextstring (HTML)no–Printed
notesstringno–Internal, not on the PDF
footerstring (HTML)no–Printed
linesLineInput[]yes–At least one line item; discount is a percentage (0–100)

Response: 201 { data: Quote }

  • Document category check (403/400), plan limit checkDocumentLimit (403), customer must belong to the company (404).
  • Quote number allocated atomically from the AN number range; totals calculated through calculateDocumentTotals with percentage discounts. Audit QUOTE_CREATED_VIA_API. Status is always DRAFT.
  • Gross prices (pricesIncludeTax: true): VAT is extracted from the gross amount per tax rate, and the document total is the sum of the gross line amounts (3 × €19.99 = €59.97). lineTotal stays net, as do all exports and the e-invoice.
GET/api/v1/quotes/{id}— Read quote details

Scope: quotes:read

Response: { data: Quote }

  • 404 "Quote not found" for unknown IDs or another company's record.
PUT/api/v1/quotes/{id}— Update a quote draft

Scope: quotes:write

Body fields

FieldTypeRequiredDefaultDescription
customerId, documentCategoryId, issueDate, validUntil, servicePeriodStart, servicePeriodEnd, reverseCharge, headerText, notes, footermixedno–All optional; null clears documentCategoryId/servicePeriod* fields
pricesIncludeTax / prices_include_taxbooleanno–Changes the price mode: VAT and totals are recalculated from the prices; the prices themselves stay unchanged. Without a value the stored price mode is kept. Only true/false, otherwise 400.
linesLineInput[]no–Replaces all line items

Response: { data: Quote }

  • Drafts only: DRAFT, lockedAt = null, convertedToInvoiceId = null; otherwise 409. The dashboard has no dedicated quote edit route. This route provides editing with the same state rules as deletion.
  • Header and line items are written conditionally in one transaction; a concurrent change returns 409. Audit QUOTE_UPDATED_VIA_API.
DELETE/api/v1/quotes/{id}— Delete a quote draft

Scope: quotes:write

Response: { data: { id, deleted: true } }

  • DRAFT only, unlocked and unconverted (conditional deleteMany); otherwise 409. Audit QUOTE_DELETED_VIA_API.
POST/api/v1/quotes/{id}/status— Accept or reject a quote

Scope: quotes:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)yes–Only ACCEPTED and REJECTED are allowedACCEPTED | REJECTED

Response: 200 { data: Quote }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403.
  • CONVERTED cannot be set directly (400: invoice status results only from conversion); EXPIRED is display-only.
  • Already converted quote → 409; invalid transition, such as ACCEPTED → ACCEPTED, → 409; unknown value → 400 with allowedValues. Audit QUOTE_STATUS_CHANGED_VIA_API.
POST/api/v1/quotes/{id}/send— Send a quote by email

Scope: quotes:write

Body fields

FieldTypeRequiredDefaultDescription
recipientEmail / recipient_emailstringnoCustomer's email address
cc, bccstringno–

Response: 200 { data: { quoteId, quoteNumber, status, sentTo, cc, bcc } }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403.
  • PDF from lib/quote-pdf.ts, email type QUOTE with an attachment; conditional DRAFT → SENT only after successful delivery.
  • lockDocument("QUOTE") + archiveDistributedPdfAsInitialVersion store the sent attachment as version 1. No recipient → 400; delivery error → 500. Audit QUOTE_SENT_VIA_API.
GET/api/v1/quotes/{id}/pdf— Download a quote PDF

Scope: quotes:read

Response: application/pdf (binary), Content-Disposition inline, X-PDF-Source: s3-cache | generated.

  • Same renderer as the dashboard and email (loadOrGenerateQuotePdf). Fingerprint cache enabled; drafts are never cached. Audit PDF_DOWNLOADED_VIA_API. 404 "Quote not found".
POST/api/v1/quotes/{id}/convert— Convert a quote to an invoice or order confirmation

Scope: quotes:writeinvoices:write

Body fields

FieldTypeRequiredDefaultDescription
targetstring (Enum)yes–"invoice" or "order-confirmation"invoice | order-confirmation

Response: 201 { data: { target, quoteId, invoice: {…} } } or { target, quoteId, orderConfirmation } }

  • In addition to quotes:write, requires the target scope: invoices:write for target "invoice", order-confirmations:write for target "order-confirmation". Checked with hasScope and the relevant constant in the route. Missing target scope → 403 with requiredScopes.
  • invoice: as in convertQuoteToInvoice. Claims the quote atomically (CONVERTED + convertedToInvoiceId), creates an invoice draft with a placeholder number, derives its due date from payment terms, converts percentage discounts to absolute invoice discounts, and uses invoice templates rather than quote text.
  • order-confirmation: as in createOrderConfirmationFromQuote. Creates an order confirmation with the quote's line items and percentage discounts; notes is the quote's closing text. The quote remains unchanged and can still be converted.
  • Already converted/rejected → 409. Audit QUOTE_CONVERTED_VIA_API + INVOICE_CREATED_FROM_QUOTE_VIA_API or ORDER_CONFIRMATION_CREATED_VIA_API. Webhook INVOICE_CREATED only for target invoice.
Order confirmations9 endpoints · order-confirmations:read, order-confirmations:write

Order confirmations, including delivery, status changes and conversion to an invoice or order.

MethodPathScopeSummary
GET/api/v1/order-confirmationsorder-confirmations:readList order confirmations
POST/api/v1/order-confirmationsorder-confirmations:writeCreate an order confirmation
GET/api/v1/order-confirmations/{id}order-confirmations:readRead order confirmation details
PUT/api/v1/order-confirmations/{id}order-confirmations:writeUpdate an order confirmation draft
DELETE/api/v1/order-confirmations/{id}order-confirmations:writeDelete an order confirmation draft
POST/api/v1/order-confirmations/{id}/statusorder-confirmations:writeSet an order confirmation's status
POST/api/v1/order-confirmations/{id}/sendorder-confirmations:writeSend an order confirmation by email
GET/api/v1/order-confirmations/{id}/pdforder-confirmations:readDownload an order confirmation PDF
POST/api/v1/order-confirmations/{id}/convertorder-confirmations:write, invoices:writeConvert an order confirmation to an invoice or order
GET/api/v1/order-confirmations— List order confirmations

Scope: order-confirmations:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–DRAFT | SENT | CONFIRMED | IN_PROGRESS | COMPLETED | CANCELLED
customer_id / customerIdstringno–
searchstringno–Order confirmation number and customer name
from, toISO dateno–By issueDate
category_idstring | "uncategorized"no–
limitnumberno50
offsetnumberno0

Response: { data: OrderConfirmation[], pagination }

  • Sorted by issueDate descending. Invalid status → 400 with allowedValues.
POST/api/v1/order-confirmations— Create an order confirmation

Scope: order-confirmations:write

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–
issueDateISO datenonow
deliveryDate, validUntilISO date | nullno–
documentCategoryIdstring | nullno–
reverseChargebooleannofalse
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.
notesstringno–Printed
footer, deliveryTerms, paymentTermsstringno–
quoteId / quote_idstringno–Optional quote reference
linesLineInput[]yes–At least one line item; discount as a percentage

Response: 201 { data: OrderConfirmation }

  • Checks the document category and company ownership of the customer (404); allocates an AB number; calculates totals through calculateDocumentTotals with percentage discounts.
  • Checks the document quota with checkDocumentLimit (403), matching the dashboard. Audit ORDER_CONFIRMATION_CREATED_VIA_API. Status is always DRAFT.
  • Gross prices (pricesIncludeTax: true): VAT is extracted from the gross amount per tax rate, and the document total is the sum of the gross line amounts (3 × €19.99 = €59.97). lineTotal stays net, as do all exports and the e-invoice.
GET/api/v1/order-confirmations/{id}— Read order confirmation details

Scope: order-confirmations:read

Response: { data: OrderConfirmation }

  • 404 "Order confirmation not found".
PUT/api/v1/order-confirmations/{id}— Update an order confirmation draft

Scope: order-confirmations:write

Body fields

FieldTypeRequiredDefaultDescription
customerId, documentCategoryId, issueDate, deliveryDate, validUntil, reverseCharge, notes, footer, deliveryTerms, paymentTermsmixedno–All optional; null clears documentCategoryId/deliveryDate/validUntil
pricesIncludeTax / prices_include_taxbooleanno–Changes the price mode: VAT and totals are recalculated from the prices; the prices themselves stay unchanged. Without a value the stored price mode is kept. Only true/false, otherwise 400.
linesLineInput[]no–Replaces all line items

Response: { data: OrderConfirmation }

  • Drafts only (DRAFT), otherwise 409. Audit ORDER_CONFIRMATION_UPDATED_VIA_API.
DELETE/api/v1/order-confirmations/{id}— Delete an order confirmation draft

Scope: order-confirmations:write

Response: { data: { id, deleted: true } }

  • DRAFT only, otherwise 409. Audit ORDER_CONFIRMATION_DELETED_VIA_API.
POST/api/v1/order-confirmations/{id}/status— Set an order confirmation's status

Scope: order-confirmations:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)yes–Only transitions allowed by document status rules; COMPLETED cannot be set directlyDRAFT | SENT | CONFIRMED | IN_PROGRESS | COMPLETED | CANCELLED

Response: 200 { data: OrderConfirmation }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403 (cancelling a draft remains possible).
  • Conditional status update only while the read status and absent invoice reference remain unchanged; conflict or already converted → 409. COMPLETED results only from conversion. Audit ORDER_CONFIRMATION_STATUS_CHANGED_VIA_API.
POST/api/v1/order-confirmations/{id}/send— Send an order confirmation by email

Scope: order-confirmations:write

Body fields

FieldTypeRequiredDefaultDescription
recipientEmail / recipient_emailstringnoCustomer's email address
cc, bccstringno–

Response: 200 { data: { orderConfirmationId, confirmationNumber, status, sentTo, cc, bcc } }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403.
  • PDF from lib/order-confirmation-pdf.ts, email type ORDER_CONFIRMATION; conditional DRAFT → SENT only after successful delivery.
  • lockDocument("ORDER_CONFIRMATION") and archive the sent attachment as version 1. No recipient → 400; delivery error → 500. Audit ORDER_CONFIRMATION_SENT_VIA_API.
GET/api/v1/order-confirmations/{id}/pdf— Download an order confirmation PDF

Scope: order-confirmations:read

Response: application/pdf (binary), Content-Disposition inline, X-PDF-Source.

  • Same renderer as dashboard/email. Fingerprint cache; drafts are not cached. Audit PDF_DOWNLOADED_VIA_API.
POST/api/v1/order-confirmations/{id}/convert— Convert an order confirmation to an invoice or order

Scope: order-confirmations:writeinvoices:write

Body fields

FieldTypeRequiredDefaultDescription
targetstring (Enum)yes–"invoice" or "order"invoice | order

Response: 201 { data: { target, orderConfirmationId, invoice: {…} } } or { target, orderConfirmationId, order: {…} } }

  • In addition to order-confirmations:write, requires invoices:write for target "invoice" or orders:write for target "order", checked through hasScope in the route. Missing target scope → 403.
  • invoice: as in convertOrderConfirmationToInvoice. Checks category, at least one line item and checkDocumentLimit (403). Claims the confirmation atomically (status → COMPLETED), creates an invoice draft with a placeholder number, converts percentage discounts to absolute discounts, and sets notes to a source order confirmation reference.
  • order: uses createOrderFromOrderConfirmation (lib/orders.ts). Creates an AU-numbered order with the confirmation's items/percentage discounts and references to the confirmation and source quote. The confirmation stays unchanged.
  • Already converted → 409. Audit ORDER_CONFIRMATION_CONVERTED_VIA_API + INVOICE_CREATED_FROM_ORDER_CONFIRMATION_VIA_API. Webhook INVOICE_CREATED after commit, only for target invoice.
Delivery notes9 endpoints · delivery-notes:read, delivery-notes:write

Delivery notes without prices, including delivery and conversion to an invoice with prices added later.

MethodPathScopeSummary
GET/api/v1/delivery-notesdelivery-notes:readList delivery notes
POST/api/v1/delivery-notesdelivery-notes:writeCreate a delivery note
GET/api/v1/delivery-notes/{id}delivery-notes:readRead delivery note details
PUT/api/v1/delivery-notes/{id}delivery-notes:writeUpdate a delivery note draft
DELETE/api/v1/delivery-notes/{id}delivery-notes:writeDelete a delivery note draft
POST/api/v1/delivery-notes/{id}/statusdelivery-notes:writeSet a delivery note's status
POST/api/v1/delivery-notes/{id}/senddelivery-notes:writeSend a delivery note by email
GET/api/v1/delivery-notes/{id}/pdfdelivery-notes:readDownload a delivery note PDF
POST/api/v1/delivery-notes/{id}/convertdelivery-notes:write, invoices:writeConvert a delivery note to an invoice, adding prices
GET/api/v1/delivery-notes— List delivery notes

Scope: delivery-notes:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–DRAFT | SENT | DELIVERED | CONVERTED
customer_id / customerIdstringno–
searchstringno–Delivery note number or customer name
from, toISO dateno–issueDate ≥/≤
category_idstring | "uncategorized"no–
limitnumberno50
offsetnumberno0

Response: 200 { data: DeliveryNote[], pagination }

  • Sorted by issueDate descending. Invalid status → 400 with allowedValues.
POST/api/v1/delivery-notes— Create a delivery note

Scope: delivery-notes:write

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–
linesLineInput[]yes–At least one item; description/quantity/unit only, no prices
lines[].descriptionstringno–Required unless productId is set
lines[].quantitynumberno1
lines[].unitstringnoProduct unit or "Stk"
lines[].productIdstringno–Fills description/unit like the dashboard product selector
deliveryDateISO dateno–
shippingAddressstringno–
notesstringno–
documentCategoryIdstring | nullno–
orderIdstring | nullno–Links to an order

Response: 201 { data: DeliveryNote }

  • Assigns LS-{YEAR}-{0001}. Checks the plan's document quota (→ 403 plan_no_access).
  • Customer/order must belong to the company (→ 404); unknown productId → 400. Audit DELIVERY_NOTE_CREATED_VIA_API. Starts as DRAFT.
GET/api/v1/delivery-notes/{id}— Read delivery note details

Scope: delivery-notes:read

Response: 200 { data: DeliveryNote }

  • 404 if the delivery note does not belong to the company.
PUT/api/v1/delivery-notes/{id}— Update a delivery note draft

Scope: delivery-notes:write

Body fields

FieldTypeRequiredDefaultDescription
customerId, documentCategoryId, deliveryDate, shippingAddress, notes, orderIdmixedno–All optional; null clears documentCategoryId/deliveryDate/orderId
linesLineInput[]no–Replaces all line items and renumbers them starting at 1

Response: 200 { data: DeliveryNote }

  • Drafts only, otherwise 409. The dashboard has no delivery note edit page; the rule follows the deletion rule. Audit DELIVERY_NOTE_UPDATED_VIA_API.
DELETE/api/v1/delivery-notes/{id}— Delete a delivery note draft

Scope: delivery-notes:write

Response: 200 { data: { id, deleted: true } }

  • Drafts only, otherwise 409. Audit DELIVERY_NOTE_DELETED_VIA_API.
POST/api/v1/delivery-notes/{id}/status— Set a delivery note's status

Scope: delivery-notes:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)yes–CONVERTED cannot be set manually → 400 with a reference to /convertDRAFT | SENT | DELIVERED

Response: 200 { data: DeliveryNote }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403.
  • Audit DELIVERY_NOTE_STATUS_CHANGED_VIA_API with { status: { old, new } }.
POST/api/v1/delivery-notes/{id}/send— Send a delivery note by email

Scope: delivery-notes:write

Body fields

FieldTypeRequiredDefaultDescription
recipientEmailstringnoCustomer's email address
cc, bccstringno–

Response: 200 { data: { deliveryNoteId, status, sentTo, cc, bcc, sentAt } }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403.
  • PDF attachment (EmailType.DELIVERY), creates a SentEmail row. Then DRAFT → SENT only while unconverted; lockDocument + archiveDistributedPdfAsInitialVersion create v1.
  • Neither customer email nor recipientEmail → 400. Failed delivery → 500, without a status change.
GET/api/v1/delivery-notes/{id}/pdf— Download a delivery note PDF

Scope: delivery-notes:read

Response: 200 binary data, Content-Type application/pdf, X-PDF-Source: s3-cache|generated.

  • Same renderer as the dashboard (lib/delivery-note-pdf.ts), including fingerprint caching; drafts are never cached. Audit PDF_DOWNLOADED_VIA_API only when found.
POST/api/v1/delivery-notes/{id}/convert— Convert a delivery note to an invoice, adding prices

Scope: delivery-notes:writeinvoices:write

Body fields

FieldTypeRequiredDefaultDescription
linesPricingArray<{position, unitPrice, taxRate}>yes–At least one item; position refers to DeliveryNoteLine.position
dueDateISO datenoCustomer's payment term, otherwise company's, otherwise 14 days
pricesIncludeTaxbooleannofalsetrue = unitPrice values in linesPricing are gross prices (incl. VAT); the invoice takes over this price mode

Response: 201 { data: { deliveryNoteId, invoiceId, invoice: { id, invoiceNumber, status, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, customer, lines[] } } }

  • Claims the delivery note atomically with a 20-second budget: status → CONVERTED and convertedToInvoiceId set. Concurrent conversion receives 409.
  • Creates an invoice draft with an ENTWURF-… placeholder number, text from invoice templates and a source delivery note reference in notes. Items without matching linesPricing receive unitPrice 0 / taxRate 20.
  • Two audit rows: DELIVERY_NOTE_CONVERTED_VIA_API for DeliveryNote and INVOICE_CREATED_FROM_DELIVERY_NOTE_VIA_API for Invoice.
Orders8 endpoints · orders:read, orders:write

Long-running orders with a budget, partial deliveries and partial invoices.

MethodPathScopeSummary
GET/api/v1/ordersorders:readList orders
POST/api/v1/ordersorders:writeCreate an order
GET/api/v1/orders/{id}orders:readRead order details and statistics
PUT/api/v1/orders/{id}orders:writeUpdate an order
DELETE/api/v1/orders/{id}orders:writeDelete an order draft
POST/api/v1/orders/{id}/statusorders:writeSet an order's status
PUT/api/v1/orders/{id}/lines/{lineId}orders:writeUpdate an order line's delivered or invoiced quantity
GET/api/v1/orders/{id}/pdforders:readDownload an order PDF
GET/api/v1/orders— List orders

Scope: orders:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–DRAFT | ACTIVE | ON_HOLD | COMPLETED | CANCELLED
customer_id / customerIdstringno–
searchstringno–Order number, title or customer name
category_idstring | "uncategorized"no–
limitnumberno50
offsetnumberno0

Response: 200 { data: Order[], pagination }

  • Sorted by createdAt descending.
POST/api/v1/orders— Create an order

Scope: orders:write

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–
namestringyes–Order title
linesLineInput[]yes–At least one
lines[].descriptionstringno–Required unless productId is provided
lines[].quantitynumberno1
lines[].unitstringnoProduct unit or "Stk"
lines[].unitPricenumbernoProduct price or 0
lines[].taxRatenumbernoProduct tax rate or 20
lines[].discountnumberno0Percentage, 0–100
lines[].lineTypestring (Enum)noPRODUCTPRODUCT | SERVICE | DISCOUNT_PERCENT | DISCOUNT_ABSOLUTE | SHIPPING | ADVANCE_PAYMENT | CREDIT | TEXT | SUBTOTAL | PAGEBREAK
lines[].productIdstringno–
description, notesstringno–
documentCategoryIdstring | nullno–
startDate, endDateISO date | nullno–
quoteId, orderConfirmationIdstringno–Must belong to the company (→ 404)
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.

Response: 201 { data: Order }

  • Assigns AU-{YEAR}-{0001}. totalBudget is calculated from line items as a net total through calculateDocumentTotals (percent mode); deduction lines reduce the budget.
  • With productId and without unitPrice, the item price is converted to the order's price mode if the item uses a different one (item tax rate, rounded to the cent).
  • Checks the document quota with checkDocumentLimit, matching the dashboard. Audit ORDER_CREATED_VIA_API. Starts as DRAFT with deliveredQty/invoicedQty at 0.
GET/api/v1/orders/{id}— Read order details and statistics

Scope: orders:read

Response: 200 { data: Order & { stats: OrderStats, invoices: [...], deliveryNotes: [...] } }

  • stats matches getOrderStats on the detail page. Deduction, text and subtotal lines are excluded from quantity progress.
PUT/api/v1/orders/{id}— Update an order

Scope: orders:write

Body fields

FieldTypeRequiredDefaultDescription
name, description, notesstringno–
documentCategoryIdstring | nullno–
startDate, endDateISO date | nullno–
pricesIncludeTax / prices_include_taxbooleanno–Changes the price mode: VAT and totals are recalculated from the prices; the prices themselves stay unchanged. Without a value the stored price mode is kept. Only true/false, otherwise 400.
linesLineInput[]no–Replaces all line items (deliveredQty/invoicedQty restart at 0); totalBudget is recalculated

Response: 200 { data: Order }

  • DRAFT and ACTIVE only, otherwise 409. The customer cannot be changed. Audit ORDER_UPDATED_VIA_API.
DELETE/api/v1/orders/{id}— Delete an order draft

Scope: orders:write

Response: 200 { data: { id, deleted: true } }

  • Drafts only, otherwise 409. Audit ORDER_DELETED_VIA_API.
POST/api/v1/orders/{id}/status— Set an order's status

Scope: orders:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)yes–DRAFT | ACTIVE | ON_HOLD | COMPLETED | CANCELLED

Response: 200 { data: Order }

  • When the document leaves draft status, it counts towards the plan document quota: an exhausted quota returns 403 (cancelling a draft remains possible).
  • The first transition out of DRAFT locks the order (lockDocument: lockedAt + v1 snapshot). Idempotent: reactivation from ON_HOLD/COMPLETED does not create another v1.
  • Audit ORDER_STATUS_CHANGED_VIA_API.
PUT/api/v1/orders/{id}/lines/{lineId}— Update an order line's delivered or invoiced quantity

Scope: orders:write

Body fields

FieldTypeRequiredDefaultDescription
deliveredQuantitynumberno–≥ 0
invoicedQuantitynumberno–≥ 0; at least one of the two is required

Response: 200 { data: { id, orderId, position, description, quantity, unit, unitPrice, taxRate, discount, discountMode: "percent", lineType, lineTotal, deliveredQty, invoicedQty } }

  • Matches updateOrderLineDeliveredQty/updateOrderLineInvoicedQty on the detail page. The line must belong to this order and company, otherwise 404. No quantity supplied → 400.
  • Audit ORDER_LINE_QUANTITY_UPDATED_VIA_API on the order, with lineId.
GET/api/v1/orders/{id}/pdf— Download an order PDF

Scope: orders:read

Response: 200 binary data, Content-Type application/pdf, X-PDF-Source.

  • Same renderer as the dashboard (lib/order-pdf.ts), including fingerprint caching. Shows ordered/delivered/invoiced quantities and progress. Audit PDF_DOWNLOADED_VIA_API only when found.
Recurring invoices10 endpoints · recurring:read, recurring:write

Schedules for automatically generated invoices: subscriptions, maintenance contracts and rent.

MethodPathScopeSummary
GET/api/v1/recurring-schedulesrecurring:readList schedules
POST/api/v1/recurring-schedulesrecurring:writeCreate a recurring invoice schedule
GET/api/v1/recurring-schedules/{id}recurring:readRead schedule details and generated invoices
PUT/api/v1/recurring-schedules/{id}recurring:writeUpdate a schedule
DELETE/api/v1/recurring-schedules/{id}recurring:writeDelete a schedule
POST/api/v1/recurring-schedules/{id}/statusrecurring:writeSet a schedule's status
POST/api/v1/recurring-schedules/{id}/archiverecurring:writeArchive a schedule
POST/api/v1/recurring-schedules/{id}/restorerecurring:writeRestore an archived schedule
POST/api/v1/recurring-schedules/{id}/generaterecurring:writeGenerate an invoice from the schedule now
POST/api/v1/recurring-schedules/{id}/recalculaterecurring:writeRecalculate the next generation date
GET/api/v1/recurring-schedules— List schedules

Scope: recurring:read

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–ACTIVE | PAUSED | ENDED | ARCHIVED
customer_idstringno–
include_archivedbooleannofalse
limitnumberno50
offsetnumberno0

Response: { data: Schedule[], meta: { total, limit, offset, hasMore } }

  • Archived schedules are hidden unless status or include_archived=true is supplied. Sorted by nextGenerationDate ascending, then createdAt descending.
POST/api/v1/recurring-schedules— Create a recurring invoice schedule

Scope: recurring:write

Plan feature: recurringInvoices

Body fields

FieldTypeRequiredDefaultDescription
documentLocale / document_localestring (Enum)no–On creation only: explicit document language takes precedence over customer/company defaults, then German. Derived documents retain the source language. The response contains documentLocale and documentTextVersion; editing does not change the stored profile.de | en
customerIdstringyes–
frequencystring (Enum)yes–WEEKLY | BIWEEKLY | MONTHLY | QUARTERLY | SEMIANNUALLY | ANNUALLY
startDateISO dateyes–
linesLineInput[]yes–At least one line item; each accepts description (required), quantity, unitPrice, taxRate (required), discount (absolute), lineType and articleNumber
namestringno"{customer} - {frequency} - {start date}"
descriptionstringno–
intervalMultipliernumberno11–99
dayOfMonthnumberno–1–31
dayOfWeeknumberno–0–6; stored without shifting the date
useLastDayOfMonthbooleannofalseSets dayOfMonth to null
endDateISO dateno–
maxOccurrencesnumberno–≥ 1
createAsDraftbooleannofalse
autoSendEmailbooleannotrue
notifyOnCreatebooleannofalse
markAsPaidbooleannofalse
emailCc, emailBccstringno–Comma-separated addresses, normalised
taxExemptionReasonstring (Enum)noNONENONE | SMALL_BUSINESS | REVERSE_CHARGE_EU | REVERSE_CHARGE_EU_NO_VAT | THIRD_COUNTRY | INTRA_COMMUNITY | EXPORT_DELIVERY | REVERSE_CHARGE_13B | INTERNAL_SUPPLY | OTHER_EXEMPTION
taxExemptionNotestringno–
taxCountrystring (ISO)noinferred from tax ratesEU codes only (AT, DE, …). Other values are not adopted: the country is inferred from tax rates, or left empty. The response contains the stored value.
headerText, notes, footerstringno–
paymentTermDaysnumberno–0–365
discountPercentnumberno–0–100
discountDaysnumberno–0–365
orderNumber, buyerReference, externalIdstringno–
totalDiscountPercentnumberno–0–100
isOSS, showServiceDateNoticebooleanno–
documentCategoryIdstring | nullno–
pricesIncludeTax / prices_include_taxbooleannofalsePrice mode: true = unit prices and amount discounts include VAT (gross prices, B2C), false = net prices. Without a value: net — even if the company defaults to gross prices. Only true/false, otherwise 400.

Response: 201 { data: Schedule }

  • Plan gate recurringInvoices (403). Checks customer (404) and document category (400). nextGenerationDate is the start date if in the future, otherwise calculated from the frequency.
  • Audit RECURRING_SCHEDULE_CREATED_VIA_API.
GET/api/v1/recurring-schedules/{id}— Read schedule details and generated invoices

Scope: recurring:read

Response: { data: Schedule & { generatedInvoices: [{ id, invoiceNumber, status, issueDate, grossTotal }] } }

  • nextGenerationDate and generatedCount are part of Schedule.
PUT/api/v1/recurring-schedules/{id}— Update a schedule

Scope: recurring:write

Body fields

FieldTypeRequiredDefaultDescription
(alle Felder von POST)mixedno–All optional; only supplied fields change. null clears endDate, maxOccurrences, dayOfMonth, dayOfWeek, paymentTermDays, discountDays, discountPercent and totalDiscountPercent. status is not accepted here.

Response: { data: Schedule }

  • Changing the cadence (frequency, intervalMultiplier, dayOfMonth, dayOfWeek, useLastDayOfMonth, startDate) recalculates nextGenerationDate. A new customer is checked (404) and the category validated (400).
  • Without pricesIncludeTax the stored price mode is kept. Generated invoices take the schedule's price mode.
  • As on creation, taxCountry accepts only EU codes. Other values fall back to the country inferred from tax rates, using the schedule's stored items if lines are omitted. The response contains the resulting stored value.
  • Audit RECURRING_SCHEDULE_UPDATED_VIA_API.
DELETE/api/v1/recurring-schedules/{id}— Delete a schedule

Scope: recurring:write

Response: { data: { id, deleted: true } }

  • Only if no invoices have been generated; otherwise 409 with archiveEndpoint. Audit RECURRING_SCHEDULE_DELETED_VIA_API.
POST/api/v1/recurring-schedules/{id}/status— Set a schedule's status

Scope: recurring:write

Body fields

FieldTypeRequiredDefaultDescription
statusstring (Enum)yes–ACTIVE | PAUSED | ENDED

Response: 200 { data: Schedule }

  • ENDED → ACTIVE is blocked (409). On activation, a future start date takes precedence; resuming from PAUSED recalculates from today. ENDED clears nextGenerationDate. ARCHIVED uses /archive.
  • Audit RECURRING_SCHEDULE_STATUS_CHANGED_VIA_API.
POST/api/v1/recurring-schedules/{id}/archive— Archive a schedule

Scope: recurring:write

Response: 200 { data: Schedule }

  • Sets ARCHIVED and clears nextGenerationDate. Already archived → 409. Audit RECURRING_SCHEDULE_ARCHIVED_VIA_API.
POST/api/v1/recurring-schedules/{id}/restore— Restore an archived schedule

Scope: recurring:write

Response: 200 { data: Schedule }

  • Only from ARCHIVED, otherwise 409; always restores to PAUSED. nextGenerationDate stays empty until activation. Audit RECURRING_SCHEDULE_RESTORED_VIA_API.
POST/api/v1/recurring-schedules/{id}/generate— Generate an invoice from the schedule now

Scope: recurring:write

Plan feature: recurringInvoices

Body fields

FieldTypeRequiredDefaultDescription
forcebooleannofalseGenerate even if the start date is in the future

Response: 201 { data: { id, invoiceNumber, status, issueDate, dueDate, currency, netTotal, taxTotal, grossTotal, customerId }, schedule: { id, status, generatedCount, lastGeneratedAt, nextGenerationDate }, warnings?: string[] }

  • If the invoice is created with a status other than draft, it immediately counts towards the document quota: an exhausted quota returns 403 plan_limit_reached without consuming a number.
  • Plan gate recurringInvoices (403). Uses the dashboard's shared logic: number allocation (ENTWURF-… for drafts); status from createAsDraft/autoSendEmail/markAsPaid; PDF email delivery for autoSendEmail including emailCc/emailBcc, with delivery failures in warnings; in-app notification RECURRING_GENERATED for notifyOnCreate.
  • Reaching maxOccurrences sets the schedule to ENDED. 409 if not ACTIVE (NOT_ACTIVE), the start date is in the future without force (BEFORE_START_DATE), the maximum is reached (MAX_OCCURRENCES), or no valid line items exist.
  • Audit RECURRING_SCHEDULE_GENERATED_VIA_API.
POST/api/v1/recurring-schedules/{id}/recalculate— Recalculate the next generation date

Scope: recurring:write

Response: 200 { data: Schedule }

  • Resets nextGenerationDate, using a future start date if present, otherwise today. ENDED/ARCHIVED → 409. Audit RECURRING_SCHEDULE_RECALCULATED_VIA_API.
Documents (file storage)10 endpoints · documents:read, documents:write

Central file storage for supporting documents, including direct S3 uploads.

MethodPathScopeSummary
GET/api/v1/documentsdocuments:readList documents
POST/api/v1/documentsdocuments:writeUpload a document directly (Base64)
POST/api/v1/documents/upload-urldocuments:writeRequest a presigned S3 upload URL
POST/api/v1/documents/confirmdocuments:writeComplete a direct upload and create the document
GET/api/v1/documents/{id}documents:readRead document metadata
GET/api/v1/documents/{id}/downloaddocuments:readDownload document content
PUT/api/v1/documents/{id}documents:writeUpdate document metadata
POST/api/v1/documents/{id}/archivedocuments:writeArchive a document
POST/api/v1/documents/{id}/unarchivedocuments:writeRestore a document from the archive
DELETE/api/v1/documents/{id}documents:writeDelete a document
GET/api/v1/documents— List documents

Scope: documents:read

Query parameters

FieldTypeRequiredDefaultDescription
typestring (Enum)no–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
archivedstring ("true"|"false"|"all")nofalse
invoice_id, customer_idstringno–
category_idstring | "uncategorized"no–
searchstringno–Name, description or tag
limitnumberno50
offsetnumberno0

Response: { data: Document[], meta: { total, limit, offset, hasMore } }

  • Sorted by createdAt descending. File contents are never included.
POST/api/v1/documents— Upload a document directly (Base64)

Scope: documents:write

Body fields

FieldTypeRequiredDefaultDescription
namestringyes–
mimeTypestringyes–Allowlist: PDF, PNG, JPEG, GIF, WebP, DOC(X), XLS(X), TXT, CSV
contentstring (Base64)yes–With or without a data: prefix; at most 20 MB
typestring (Enum)noOTHERINVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
descriptionstringno–
tagsstring[]no–
invoiceId, customerId, documentCategoryIdstringno–

Response: 201 { data: Document }

  • 400 FILE_TOO_LARGE above 20 MB; 400 MIME_NOT_ALLOWED outside the allowlist; 403 STORAGE_LIMIT when the plan's storage quota is exhausted.
  • Storage: S3 when STORAGE_PROVIDER=s3, otherwise Base64 in the database (502 STORAGE_FAILED on S3 error). Invoice/customer/category are checked (404/400). Audit DOCUMENT_CREATED_VIA_API.
POST/api/v1/documents/upload-url— Request a presigned S3 upload URL

Scope: documents:write

Body fields

FieldTypeRequiredDefaultDescription
fileName / namestringyes–
mimeTypestringyes–
sizenumberyes–Bytes > 0, at most 100 MB
typestring (Enum)noOTHERINVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER

Response: 200 { data: { uploadUrl, key, method: "PUT", headers: { "Content-Type" }, expiresAt } }

  • 403 STORAGE_LIMIT if the file would exceed the plan storage quota.
  • Requires S3 storage, otherwise 400 S3_REQUIRED with a reference to POST /documents. URL valid for five minutes. Does not create a document yet.
POST/api/v1/documents/confirm— Complete a direct upload and create the document

Scope: documents:write

Body fields

FieldTypeRequiredDefaultDescription
keystringyes–From /upload-url; must start with the company ID, otherwise 400 INVALID_STORAGE_KEY
namestringyes–
mimeTypestringyes–
sizenumberyes–
typestring (Enum)no–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
descriptionstringno–
tagsstring[]no–
invoiceId, customerId, documentCategoryIdstringno–

Response: 201 { data: Document }

  • The storage quota uses the size of the S3 object, not the supplied size (which is overwritten). Exceeding the quota returns 403 STORAGE_LIMIT and deletes the uploaded object; a missing uploaded object returns 400 UPLOAD_NOT_FOUND.
  • Matches confirmDirectUpload in the dashboard. Without S3 → 400 S3_REQUIRED. Unlike the original plan, there is no {id} in the path because the document does not exist before confirmation.
  • Audit DOCUMENT_CREATED_VIA_API.
GET/api/v1/documents/{id}— Read document metadata

Scope: documents:read

Response: { data: Document }

  • Metadata only.
GET/api/v1/documents/{id}/download— Download document content

Scope: documents:read

Response: S3: { data: { id, name, mimeType, url, expiresAt } }. Local: binary data with Content-Disposition attachment.

  • Presigned S3 URL, valid for one hour. Missing data → 404 (DATA_MISSING/STORAGE_FAILED).
PUT/api/v1/documents/{id}— Update document metadata

Scope: documents:write

Body fields

FieldTypeRequiredDefaultDescription
namestringno–Not empty
descriptionstringno–
typestring (Enum)no–INVOICE_PDF | RECEIPT | CONTRACT | OFFER | DELIVERY_NOTE | CORRESPONDENCE | TAX_DOCUMENT | OTHER
tagsstring[]no–
invoiceId, customerId, documentCategoryIdstring | nullno–

Response: { data: Document }

  • Metadata only; the file stays unchanged. References are checked against the company (404). Audit DOCUMENT_UPDATED_VIA_API.
POST/api/v1/documents/{id}/archive— Archive a document

Scope: documents:write

Response: 200 { data: Document }

  • Sets isArchived=true, archivedAt=now. Already archived → 409. Audit DOCUMENT_ARCHIVED_VIA_API.
POST/api/v1/documents/{id}/unarchive— Restore a document from the archive

Scope: documents:write

Response: 200 { data: Document }

  • Sets isArchived=false, archivedAt=null. Not archived → 409. Audit DOCUMENT_ARCHIVED_VIA_API, with the direction in changes.isArchived.
DELETE/api/v1/documents/{id}— Delete a document

Scope: documents:write

Response: { data: { id, deleted: true } }

  • Also deletes the S3 file; an S3 error does not prevent deletion of the database record. Audit DOCUMENT_DELETED_VIA_API.
Exports3 endpoints · exports:read, direct-debits:write

Accounting exports (CSV, DATEV, BMD, UStVA) and SEPA direct debit files.

MethodPathScopeSummary
GET/api/v1/exportsexports:readGenerate an accounting export (CSV, DATEV, BMD, UStVA)
POST/api/v1/exports/sepadirect-debits:writeCreate a SEPA batch and generate a direct debit file (PAIN.008)
GET/api/v1/exports/customersexports:readExport customers as CSV
GET/api/v1/exports— Generate an accounting export (CSV, DATEV, BMD, UStVA)

Scope: exports:read

Query parameters

FieldTypeRequiredDefaultDescription
typestring (Enum)nocsvcsv | datev | bmd | ust
yearnumbernocurrent year
monthnumberno–0–11
quarternumberno–1–4; without month/quarter, uses the full year
category_id / categorystringno–also "all"/"uncategorized"

Response: File with Content-Disposition attachment. csv/ust: text/csv. datev: text/csv (posting batch). bmd: application/zip (buchungen.csv, personenkonten.csv, hinweise.txt). With Accept: application/json, csv returns { csv, filename, summary, warnings[] } instead.

  • Identical files to /dashboard/exports, with the same document selection: taxRelevantInvoiceConditions excludes drafts and proformas, and includes cancelled invoices only with a cancellation credit note.
  • Plan gate datevExport for type=datev/bmd (403); csv and ust are included in every plan. Invalid type → 400 with allowedValues. No AuditLog, matching the dashboard.
POST/api/v1/exports/sepa— Create a SEPA batch and generate a direct debit file (PAIN.008)

Scope: direct-debits:write

Body fields

FieldTypeRequiredDefaultDescription
invoiceIdsstring[]yes–1 to 500
requestedCollectionDateISO dateyes–Must be after today (calendar day in Vienna)
mandateTypestring (Enum)noCORECustomers with a different mandate type are skippedCORE | B2B

Response: 200 by default: application/xml with Content-Disposition attachment and X-Sepa-Message-Id/-Transaction-Count/-Warnings/-Batch-Number headers. With Accept: application/json: { xml, filename, messageId, transactionCount, totalAmount, warnings[], batchId, batchNumber }.

  • Each call creates a batch (DD-YYYY-NNNN), as with the dashboard bulk action. This requires a dedicated scope rather than exports:read: its invoices are blocked from further exports until the batch is discarded (Dashboard → SEPA direct debits). The file remains stored. Collects the outstanding balance of sent or overdue invoices in euro; invoice status remains unchanged.
  • Skipped invoices appear in warnings ("RE-… (Customer): Reason"): wrong document type or status, no outstanding balance, invoice already in a batch that has not been discarded, missing or invalid IBAN, no active dated mandate, different mandate type, a used one-off mandate (OOFF), or a mandate reference outside SEPA rules (up to 35 letters, digits and + ? / - : ( ) . , ' spaces). X-Sepa-Warnings contains at most 50 entries and a note about the rest; use Accept: application/json for all warnings.
  • The company needs a valid sepaCreditorId (400 MISSING_CREDITOR_ID or INVALID_CREDITOR_ID) and a valid iban (400 MISSING_IBAN or INVALID_IBAN, including checksum). No eligible direct debits: 400 NO_VALID_TRANSACTIONS with details. None of the invoices found: 404. Audit: SEPA_EXPORT_VIA_API.
GET/api/v1/exports/customers— Export customers as CSV

Scope: exports:read

Query parameters

FieldTypeRequiredDefaultDescription
include_archived / includeArchivedbooleannofalse
formatstring (Enum)nosemicoloncomma | semicolon

Response: CSV with BOM, Content-Disposition attachment, header X-Export-Customer-Count.

  • The same 43 columns with German headers and formula neutralisation as the dashboard export. Audit CSV_EXPORT_CUSTOMERS, with apiKeyId added to changes.
Company details1 endpoint · company:read

Company details, number ranges, plan features and usage; read-only.

MethodPathScopeSummary
GET/api/v1/companycompany:readRead company details, number ranges and plan usage
GET/api/v1/company— Read company details, number ranges and plan usage

Scope: company:read

Response: { data: { id, name, address, contact, legal, tax, bank, currency, paymentTerms, dunning, branding, numberRanges, plan: { plan, subscriptionPlan, subscriptionExpiresAt, trialEndsAt, features, limits }, usage: { documents, customers, emails, storage, apiCalls, users } } }

  • Read-only, no side effects.
  • legal contains the legal form (legalForm), legal name (legalName), trading name (tradingName), court of registry (registryCourt) and, for sole proprietorships, the owner (owner) — the same details as on documents.
  • Deliberately excluded: SMTP credentials, email domain/DKIM settings, Stripe IDs, finAPI connection, API keys, BMD account configuration, admin plan overrides and raw logo storage.
Webhooks8 endpoints · webhooks:read, webhooks:write

Webhook endpoints for event notifications, Enterprise plan only. Endpoints are managed through this API only; the dashboard has no webhook editor. Every delivery is signed with HMAC-SHA256 over the unmodified JSON body using the endpoint's secret (header X-Webhook-Signature, hex), together with X-Webhook-Event, X-Webhook-Event-Id and X-Webhook-Timestamp.

MethodPathScopeSummary
GET/api/v1/webhookswebhooks:readList webhook endpoints
POST/api/v1/webhookswebhooks:writeCreate a webhook endpoint
GET/api/v1/webhooks/{id}webhooks:readRead a webhook endpoint and recent deliveries
PUT/api/v1/webhooks/{id}webhooks:writeUpdate a webhook endpoint
DELETE/api/v1/webhooks/{id}webhooks:writeDelete a webhook endpoint
POST/api/v1/webhooks/{id}/rotate-secretwebhooks:writeRotate a webhook endpoint's signing secret
POST/api/v1/webhooks/{id}/testwebhooks:writeSend a test event to a webhook endpoint
GET/api/v1/webhooks/{id}/deliverieswebhooks:readList delivery attempts for a webhook endpoint
GET/api/v1/webhooks— List webhook endpoints

Scope: webhooks:read

Plan feature: webhooks

Response: { data: [{ id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, total_deliveries, created_at, updated_at }] }

  • Enterprise plan gate (feature "webhooks"). Never returns the secret.
POST/api/v1/webhooks— Create a webhook endpoint

Scope: webhooks:write

Plan feature: webhooks

Body fields

FieldTypeRequiredDefaultDescription
namestringyes–
urlstringyes–Must resolve to a public HTTPS host (assertPublicHttpUrl)
eventsstring[]yes–Not empty; every value is checked against WebhookEventType, ignoring case and hyphens. WEBHOOK_TEST cannot be subscribed to
secretstringnogenerated as whsec_<48 hex>
max_retries / maxRetriesnumberno3Integer 0–10 (total number of attempts, at least 1)
retry_delay_ms / retryDelayMsnumberno1000Integer 100–600000; wait before retry n = retry_delay_ms · 2^n. Retries happen only within 60 minutes of the event
rate_limit_per_min / rateLimitPerMinnumber | nullnonull (unlimited)null (unlimited) or an integer 1–10000
headersobjectno–Included with every delivery
metadataobjectno–

Response: 201 { data: { id, name, url, secret, events[], is_active, max_retries, retry_delay_ms, created_at } } — the secret is returned only here

  • Audit WEBHOOK_ENDPOINT_CREATED. 400 for missing name/url/events, invalid event type, a URL failing the public HTTPS egress check (private/local host, embedded credentials or non-HTTPS), or retry settings outside the bounds (max_retries 0–10, retry_delay_ms 100–600000, rate_limit_per_min null or 1–10000). null for max_retries/retry_delay_ms means the default here.
  • Payout webhooks expose bank details only as iban_last4: the last four characters after removing whitespace, null without an IBAN. iban, bic, bankAccountHolder and bankName are omitted from embedded payout records as well (e.g. CREDIT_NOTE_CREATED/PAID), including named copies in payout metadata. Status, amounts, transaction references and other permitted metadata remain unchanged. REST credit-note and payout responses are unchanged.
GET/api/v1/webhooks/{id}— Read a webhook endpoint and recent deliveries

Scope: webhooks:read

Plan feature: webhooks

Response: { data: { id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, headers, metadata, total_deliveries, recent_deliveries: [...] (last ten), created_at, updated_at } }

  • 404 if not found or owned by another company.
PUT/api/v1/webhooks/{id}— Update a webhook endpoint

Scope: webhooks:write

Plan feature: webhooks

Body fields

FieldTypeRequiredDefaultDescription
name, url, eventsmixedno–All optional/partial
is_active / isActivebooleanno–
max_retries / maxRetriesnumberno–Integer 0–10 (total number of attempts, at least 1)
retry_delay_ms / retryDelayMsnumberno–Integer 100–600000; wait before retry n = retry_delay_ms · 2^n. Retries happen only within 60 minutes of the event
rate_limit_per_min / rateLimitPerMinnumber | nullno–null (unlimited) or an integer 1–10000
headers, metadataobjectno–

Response: 200 { data: { id, name, url, events[], is_active, max_retries, retry_delay_ms, rate_limit_per_min, updated_at } } — rate_limit_per_min is new in the response

  • 404 if not found. 400 for an empty/invalid url, non-array events, invalid event type or retry settings outside the bounds (max_retries 0–10, retry_delay_ms 100–600000, rate_limit_per_min null or 1–10000). null for max_retries/retry_delay_ms is rejected (previously stored silently as 0); null for rate_limit_per_min removes the limit.
  • A secret in the body is rejected (400, code secret_not_updatable) instead of being silently ignored as before; nothing is changed.
  • Custom headers cannot override X-Webhook-Signature, X-Webhook-Event, X-Webhook-Event-Id, X-Webhook-Timestamp, Host or Content-Length, in any letter case.
  • Audit WEBHOOK_ENDPOINT_UPDATED with changes = { apiKeyId, <field>: { old, new } } for each field actually changed. Header changes are logged only as { old_keys, new_keys }; values are never logged because they can contain secrets such as Authorization tokens.
DELETE/api/v1/webhooks/{id}— Delete a webhook endpoint

Scope: webhooks:write

Plan feature: webhooks

Response: 200 { success: true }

  • Hard delete, cascading WebhookDelivery rows through the foreign key. Audit WEBHOOK_ENDPOINT_DELETED. 404 if not found.
POST/api/v1/webhooks/{id}/rotate-secret— Rotate a webhook endpoint's signing secret

Scope: webhooks:write

Plan feature: webhooks

Body fields

FieldTypeRequiredDefaultDescription
secretstringnoomitted: Claribill generates whsec_<48 hex> and returns it onceNew secret, 32–256 visible ASCII characters without spaces. Never returned, not even in error messages
expected_updated_at / expectedUpdatedAtstring (ISO timestamp)no–updated_at from GET /webhooks/{id} (ISO 8601 with time and zone); if the endpoint changed since → 409 endpoint_modified. Recommended even without a provided secret

Response: 200 { data: { id, rotated: true, secret_source: "provided" | "generated", secret (only when generated), updated_at } } with Cache-Control: no-store

  • Takes effect immediately for every following attempt, including retries of deliveries already in progress. A request already in flight during the rotation still carries the old signature. Claribill does not sign with the old secret in parallel; coordinate the switch with the receiver as described in the operations runbook.
  • Audit WEBHOOK_SECRET_ROTATED in the same commit, with a marker and the source (provided/generated) only, never the secret or a hash. GET responses still never include the secret.
  • 400 invalid secret, invalid timestamp or body not a JSON object; 404 not found or another company's endpoint; 409 endpoint_modified with the current updated_at.
POST/api/v1/webhooks/{id}/test— Send a test event to a webhook endpoint

Scope: webhooks:write

Plan feature: webhooks

Response: 200 { data: { delivery_id, event_id, event_type: "WEBHOOK_TEST", status: "SUCCESS" | "FAILED", response_status, response_time_ms, error_message } }

  • Exactly one signed attempt to exactly this endpoint, without retries and without broadcasting to other endpoints. The body is ignored.
  • Fixed payload { event: "WEBHOOK_TEST", event_id: "evt_test_…", timestamp, data: { test: true, message } } without a business object: no invoice, payment, reminder, customer or email is created. The receiver must acknowledge WEBHOOK_TEST without processing it.
  • The result is also in the delivery log (event_type WEBHOOK_TEST). A failure at the receiver is status FAILED in a 200 response. Overall limit of 10 seconds for name resolution, connection and response headers; Claribill does not read the response body. The test counts towards the endpoint's rate_limit_per_min and can delay real events there.
  • Audit WEBHOOK_TEST_SENT. 404 not found or another company's endpoint; 409 endpoint_inactive; 429 test_rate_limited (at most 5 tests per minute per endpoint, also for parallel calls; Retry-After gives the seconds until the next free slot).
GET/api/v1/webhooks/{id}/deliveries— List delivery attempts for a webhook endpoint

Scope: webhooks:read

Plan feature: webhooks

Query parameters

FieldTypeRequiredDefaultDescription
statusstring (Enum)no–PENDING | SUCCESS | FAILED | RETRYING
event_typestring (Enum WebhookEventType)no–Also WEBHOOK_TEST for test deliveries
limitnumberno50
offsetnumberno0

Response: { data: [{ id, event_type, event_id, status, attempts, last_attempt_at, next_retry_at, response_status, response_body, response_time_ms, error_message, created_at, completed_at }], pagination: { total, limit, offset, has_more } }

  • 404 if the endpoint is not found. Invalid status/event_type → 400 with allowedValues, previously an empty result or possible 500.
Blog (platform admins only)32 endpoints · blog:read, blog:write, blog:publish, blog:moderate

Internal CMS for the Claribill blog. Uses lib/blog/api-auth.ts; the API key must also belong to a platform admin. Not a customer feature; only methods, paths and scopes are listed here.

MethodPathScopeSummary
GET/api/v1/blog/postsblog:readList blog posts
POST/api/v1/blog/postsblog:writeCreate a blog post
GET/api/v1/blog/connectionblog:readVerify blog connection
GET/api/v1/blog/posts/{id}blog:readRead a blog post
PATCH/api/v1/blog/posts/{id}blog:writeUpdate a blog post
DELETE/api/v1/blog/posts/{id}blog:writeDelete a blog post
GET/api/v1/blog/posts/by-slug/{slug}blog:readRead a blog post by slug
POST/api/v1/blog/posts/{id}/publishblog:publishPublish a blog post
DELETE/api/v1/blog/posts/{id}/publishblog:publishUnpublish a blog post
POST/api/v1/blog/posts/{id}/scheduleblog:publishSchedule a blog post for a later time
GET/api/v1/blog/categoriesblog:readList blog categories
POST/api/v1/blog/categoriesblog:writeCreate a blog category
GET/api/v1/blog/categories/{id}blog:readRead a blog category
PATCH/api/v1/blog/categories/{id}blog:writeUpdate a blog category
DELETE/api/v1/blog/categories/{id}blog:writeDelete a blog category
GET/api/v1/blog/tagsblog:readList blog tags
POST/api/v1/blog/tagsblog:writeCreate a blog tag
GET/api/v1/blog/tags/{id}blog:readRead a blog tag
PATCH/api/v1/blog/tags/{id}blog:writeUpdate a blog tag
DELETE/api/v1/blog/tags/{id}blog:writeDelete a blog tag
GET/api/v1/blog/mediablog:readList the media library
POST/api/v1/blog/mediablog:writeUpload media
GET/api/v1/blog/media/{id}blog:readRead media
POST/api/v1/blog/ai/full-postblog:writeStart AI blog post generation
POST/api/v1/blog/ai/full-post/jobsblog:writeCreate an AI generation job
GET/api/v1/blog/ai/full-post/jobs/{id}blog:readRead an AI generation job's status
POST/api/v1/blog/ai/full-post/jobs/{id}/resumeblog:writeResume an interrupted AI generation job
POST/api/v1/blog/posts/{id}/translationsblog:writeCreate a translation draft in the other language
GET/api/v1/blog/posts/{id}/translation-reviewblog:readRead the translation review state and content hashes
POST/api/v1/blog/posts/{id}/translation-reviewblog:publishApprove a reviewed translation against the current source content
PUT/api/v1/blog/categories/{id}/translationsblog:writeSave the English name, slug and description of a category
PUT/api/v1/blog/tags/{id}/translationsblog:writeSave the English name and slug of a tag
GET/api/v1/blog/posts— List blog posts

Scope: blog:read

Response: { posts: BlogPost[], pagination: { total, limit, offset } }

POST/api/v1/blog/posts— Create a blog post

Scope: blog:write

HTTP headers

FieldTypeRequiredDefaultDescription
Idempotency-Keystringno–Optional, 8–200 characters from A–Z, a–z, 0–9, . _ : -. Per company and endpoint: the same key and JSON body return the same article in its current state (201, Idempotent-Replayed: true), including concurrent requests. A different body or invalid key returns 422; a deleted article returns 409 idempotency_key_post_deleted. JSON field order does not matter; ignored fields are also compared. Retained for at least 30 days; after cleanup, the same key can create a new article.

Response: 201 BlogPost (without data envelope)

  • PUBLISHED and SCHEDULED additionally require blog:publish; authentication, scopes and quota checks also apply to replays.
  • Without Idempotency-Key, each request creates a new article. Replays do not dispatch webhooks or invalidate caches again. Existing webhook dispatch does not guarantee delivery: interruption after commit can prevent the first event.
GET/api/v1/blog/connection— Verify blog connection

Scope: blog:read

Response: BlogConnection { companyId, scopes, locales, revisionHeader, adapterVersion }

GET/api/v1/blog/posts/{id}— Read a blog post

Scope: blog:read

Response: BlogPost (without data envelope)

PATCH/api/v1/blog/posts/{id}— Update a blog post

Scope: blog:write

HTTP headers

FieldTypeRequiredDefaultDescription
X-Claribill-Expected-Updated-Atstringno–Optional: exact ISO updatedAt value from the last readback; stale revisions are rejected atomically with 409.

Response: BlogPost (without data envelope)

  • Transitions to or from PUBLISHED additionally require blog:publish.
DELETE/api/v1/blog/posts/{id}— Delete a blog post

Scope: blog:write

HTTP headers

FieldTypeRequiredDefaultDescription
X-Claribill-Expected-Updated-Atstringno–Optional: exact ISO updatedAt value from the last readback; stale revisions are rejected atomically with 409.

Response: 200 { ok: true }

GET/api/v1/blog/posts/by-slug/{slug}— Read a blog post by slug

Scope: blog:read

Response: BlogPost (without data envelope)

POST/api/v1/blog/posts/{id}/publish— Publish a blog post

Scope: blog:publish

HTTP headers

FieldTypeRequiredDefaultDescription
X-Claribill-Expected-Updated-Atstringno–Optional: exact ISO updatedAt value from the last readback; stale revisions are rejected atomically with 409.

Response: 200 BlogPost (without data envelope)

DELETE/api/v1/blog/posts/{id}/publish— Unpublish a blog post

Scope: blog:publish

HTTP headers

FieldTypeRequiredDefaultDescription
X-Claribill-Expected-Updated-Atstringno–Optional: exact ISO updatedAt value from the last readback; stale revisions are rejected atomically with 409.

Response: BlogPost (without data envelope)

POST/api/v1/blog/posts/{id}/schedule— Schedule a blog post for a later time

Scope: blog:publish

Response: 200 BlogPost (without data envelope)

GET/api/v1/blog/categories— List blog categories

Scope: blog:read

Response: { categories: BlogCategory[] }

POST/api/v1/blog/categories— Create a blog category

Scope: blog:write

Response: 201 { id, slug, name }

GET/api/v1/blog/categories/{id}— Read a blog category

Scope: blog:read

Response: BlogCategory (record without data envelope)

PATCH/api/v1/blog/categories/{id}— Update a blog category

Scope: blog:write

Response: BlogCategory (record without data envelope)

DELETE/api/v1/blog/categories/{id}— Delete a blog category

Scope: blog:write

Response: 200 { ok: true }

GET/api/v1/blog/tags— List blog tags

Scope: blog:read

Response: { tags: BlogTag[] }

POST/api/v1/blog/tags— Create a blog tag

Scope: blog:write

Response: 201 { id, slug, name }

GET/api/v1/blog/tags/{id}— Read a blog tag

Scope: blog:read

Response: BlogTag (record without data envelope)

PATCH/api/v1/blog/tags/{id}— Update a blog tag

Scope: blog:write

Response: BlogTag (record without data envelope)

DELETE/api/v1/blog/tags/{id}— Delete a blog tag

Scope: blog:write

Response: 200 { ok: true }

GET/api/v1/blog/media— List the media library

Scope: blog:read

Response: { media: BlogMedia[] }

POST/api/v1/blog/media— Upload media

Scope: blog:write

Response: 201 BlogMedia without width/height (without data envelope)

GET/api/v1/blog/media/{id}— Read media

Scope: blog:read

Response: BlogMedia (without data envelope)

POST/api/v1/blog/ai/full-post— Start AI blog post generation

Scope: blog:write

Response: 200 { draft, ai: { model, promptHash } } — synchronous generation; use the job endpoints for long-running requests

POST/api/v1/blog/ai/full-post/jobs— Create an AI generation job

Scope: blog:write

Response: 202 { job: Job }

GET/api/v1/blog/ai/full-post/jobs/{id}— Read an AI generation job's status

Scope: blog:read

Response: { job: Job }

POST/api/v1/blog/ai/full-post/jobs/{id}/resume— Resume an interrupted AI generation job

Scope: blog:write

Response: 202 { job: Job } (200 if the job has already completed)

POST/api/v1/blog/posts/{id}/translations— Create a translation draft in the other language

Scope: blog:write

Response: { id, locale, status }

GET/api/v1/blog/posts/{id}/translation-review— Read the translation review state and content hashes

Scope: blog:read

Response: { state, postHash, sourceHash, sourceId }

POST/api/v1/blog/posts/{id}/translation-review— Approve a reviewed translation against the current source content

Scope: blog:publish

Response: 200 { ok: true }

PUT/api/v1/blog/categories/{id}/translations— Save the English name, slug and description of a category

Scope: blog:write

Response: 200 { id, categoryId, locale, slug, name, description }

PUT/api/v1/blog/tags/{id}/translations— Save the English name and slug of a tag

Scope: blog:write

Response: 200 { id, tagId, locale, slug, name }

Metadata and discovery1 endpoint

Machine-readable description of the API itself.

MethodPathScopeSummary
GET/api/v1/openapi.json–Load the machine-readable OpenAPI 3.0 document for the entire v1 API
GET/api/v1/openapi.json— Load the machine-readable OpenAPI 3.0 document for the entire v1 API

Public; no authentication required.

Query parameters

FieldTypeRequiredDefaultDescription
localestring (Enum)nodeDescription language; technical fields and examples remain unchanged. Unsupported languages return 400.de | en

Response: 200 application/json — OpenAPI 3.0.3 document generated from this catalogue (lib/api/openapi.ts).

  • Publicly accessible; no authentication required. Cache-Control: public, max-age=300.

Open topic in help

VAT validation history

All VAT ID checks are logged automatically.

Stored data:

  • VAT ID and country code
  • Validation result: valid or invalid
  • Company name and address returned by VIES
  • Timestamp and user
  • Link to the customer, if available

Access:

  1. Go to Customers
  2. Click VAT history

Use:

  • Evidence for tax authorities
  • Compliance documentation
  • Traceability of reverse-charge decisions

Open topic in help

Notifications

Claribill notifies you in the app and by email about important events, such as incoming payments, overdue invoices or accepted quotes.

Settings:

Under Settings → Notifications, choose whether to receive each event in the app, by email or through both channels.

Customise notification text:

Under Settings → Notification templates, edit each notification template and send yourself a Test email using its most recently saved version.

In the app:

Unread notifications appear through the bell icon in the dashboard.

Open topic in help

Accounting (BMD)

Assign sales to the relevant BMD accounts so that exports can be imported into BMD NTCS.

Configuration:

Under Settings → Accounting, set the default revenue account for domestic sales and the BMD tax codes for domestic and EU reverse-charge transactions.

Use:

The mapping is applied automatically to the BMD export described under Exports. DATEV exports use each customer's debtor account number instead.

Open topic in help

Email outbox

Keep track of automatically sent emails.

Overview:

Under Settings → Email outbox, view logged emails and their delivery status, including Sent and Failed.

Resend:

Supported failed document emails can be resent from the outbox. New entries reuse the saved recipient, language, text and PDF. If the document has changed, review it and send it again from its document page.

Historical entries without saved content are labelled accordingly and use the current document when resent. Every delivery attempt creates a new entry; the previous failed attempt remains in the history.

Uncertain delivery

Do not blindly resend when delivery is in progress or uncertain. Inspect the invoice and outbox. Reserved capacity does not expire automatically. Only owners and admins may confirm proven non-delivery; active attempts remain locked.

Open topic in help

Security and passkeys

Manage sign-in methods under Settings → Security.

Add a passkey:

  1. Click Add passkey
  2. Confirm with your fingerprint, facial recognition or device PIN
  3. The passkey appears in the list with its device name and creation date

Management:

  • Several passkeys can be used with one account
  • Remove passkeys you no longer need at any time
  • Email magic links remain available as a fallback

Open topic in help

Drafts

The central draft list at /en/dashboard/drafts contains autosaved form inputs for the current user and active company. Continue a form or confirm deletion. Autosave starts only when the form has sufficient input, for example a selected customer.

An autosaved form differs from an invoice saved with Create invoice in Draft status. Find that invoice under Invoices. Company and user boundaries also apply to autosaved forms. Autosave neither finalises nor sends a document.

Open topic in help

Roles & permissions

Decide yourself what each role in your company may do.

Adjust standard roles

Under Settings → Roles & permissions, open a role (Administrator, Accounting, Employee or External). Permissions are grouped by area: documents, master data, finance and administration. Each area (for example invoices or customers) starts collapsed and shows how many permissions are allowed. Click an area to see and change its permissions, or use the search. Grant or remove each permission individually, for example Invoices: Create, Record payments, Delivery notes: Create or Customers: Delete. Save permissions applies the changes immediately to every member of the role. Reset to default restores the original permissions.

The owner always has every permission; this role cannot be restricted.

None, Own, Categories, All

For documents, many permissions have a scope: None, Own, Categories or All. “Own” applies to documents the member created and, for viewing, to shared ones. “Categories” works like “Own” and additionally applies to every document in the categories you select for that permission; without a selection it works like “Own”. “All” applies to every document of the company.

These permissions have a scope:

  • Invoices: View, Edit, Delete drafts, Finalise, Send by email, Change status, Cancel
  • Quotes: View, Delete, Send by email, Change status
  • Order confirmations: View, Edit, Delete, Send by email, Change status
  • Orders: View, Edit, Delete, Change status
  • Delivery notes: View, Delete, Send by email, Change status
  • Recurring invoices: View; Edit, pause and resume; Delete and archive
  • Documents: View, Edit and archive, Delete
  • Document categories: Assign a category to documents

All other permissions are simply allowed or not allowed, for example creating, payments, corrections and conversions.

Categories per permission

When a permission is set to Categories, a searchable multi-select appears in its row, to the left of the level selector. The first entry is Documents without a category, followed by the document categories. Each permission has its own selection, as does each document type (invoices, quotes, order confirmations, orders, delivery notes, recurring invoices, documents). Without a selection the button reads Select categories and the permission applies to the member's own documents only. The buttons below the list (Apply to the n other “Categories” permissions in area, Apply to all n other “Categories” permissions of the role) copy the selection to other permissions already set to “Categories”. A selection once saved for the whole role keeps working and appears in the rows of those permissions.

Limit the role’s working area

At the top of each role's page (except the owner), the card Limit the role’s working area lets you set an optional limit: with the checkbox This role works in certain categories exclusively and a selection of categories (again including the entry Documents without a category), members only see and edit documents within the limit: their own and shared documents outside it are locked, new documents need one of these categories, and this applies at every level, including “All”. Without a limit the card reads “No limit”. With a limit, a permission's selection only offers categories within the limit. An empty limit blocks document access, and the company-wide lookup in payment reconciliation is not available to such roles. Roles that may Manage categories cannot have a limit.

Example: the role “Project X” may use Invoices: View in categories A and B and Invoices: Edit only in B (both at level “Categories”). Members see their own invoices and those in categories A and B, but only edit their own and those in category B. If a single member needs special permissions, create a separate role for them.

Credit notes

The Credit notes module has no levels and no category selection. Credit notes count as invoices: which credit notes a role sees is determined by the permission Invoices: View, including the categories selected there. The permissions Credit notes: View and Credit notes: Create only decide whether the role may open the Credit notes area and create credit notes.

Dependencies

Some permissions require another one. Without View, the other permissions of the area are locked. Convert to invoice requires Invoices: Create. The page shows what is missing below the permission.

Custom roles

From the Professional plan, create your own roles with New role, for example “Sales” or “Warehouse”. Choose a template, enter a name and adjust the permissions. Assign custom roles under Team, including in the invitation. A custom role can only be deleted when it is no longer assigned to anyone.

Safeguards

  • Roles and permissions are managed by anyone holding Manage roles and permissions (by default owners and administrators)
  • Nobody changes their own role
  • Nobody grants permissions or categories beyond their own
  • Every change is recorded in the audit log

Open topic in help

Uncertain delivery and reserved allowance

A draft can reserve sending capacity without counting as an issued document. In-progress or uncertain delivery does not release that capacity automatically after a timeout.

  1. Inspect the document and outbox, including delivery messages and records.
  2. Read whether the attempt is still active or its outcome is uncertain. Repeated clicks are not proof of delivery or non-delivery.
  3. Only owners and admins may confirm non-delivery after establishing that nothing was delivered and no attempt is still running.
  4. The confirmation releases only the reserved capacity; the document, number and sending record remain unchanged.
  5. If delivery remains uncertain, cancel and ask support to investigate. Active attempts remain locked and may require controlled recovery.

An error, missing status or elapsed time is not proof of non-delivery. Resolving a reservation does not send an email.

Open topic in help

REST API, MCP and webhooks

REST API

Anyone holding the API keys permission (by default owners and admins) creates company-specific API keys with selected scopes under Settings → API keys. API access starts with Starter. The complete secret is shown only once; keys can subsequently be enabled, disabled or deleted. The public reference and OpenAPI file describe methods, fields, errors, limits and side effects.

An API key belongs to the company, not to a user, and is not bound to roles or document categories. Within its scopes it reaches every document of the company, regardless of the role and categories of the person who creates it. Grant only the scopes an integration needs. Where an action needs an acting user, for example as the creator of a document, the company’s owner is used (with several owners, the one with the oldest membership). The audit log marks such actions as API actions and names the key used.

REST covers many document and master-data workflows, but not every dashboard setting or personal account function. Platform blog endpoints also require platform administrator access.

Preparing an invoice draft

POST /api/v1/invoices/prepare returns a preview and explicit create body. Preparation alone does not create or send a document. Follow its version and idempotency contract when creating afterwards.

Sending contract

The optional invoice_send_v1 contract requires operational activation. Detect availability using the documented capability endpoint. Implemented code is not proof of general activation. Never retry uncertain delivery automatically with a new key or without a key. Status and replay remain historical; resolution_decision may report a separate reviewed resolution.

MCP

The separate OAuth connection for Codex/ChatGPT provides ten tools listed in the plugin guide. It differs from the integrated dashboard assistant; do not assume it supports all of that assistant's operations.

Connecting requires a role with the permission Connect external AI apps (Settings → Roles & permissions, section AI assistant). If it is withdrawn, Claribill rejects further calls from the connected app. In addition to the OAuth scope, every tool needs the matching permission of the role, for example Invoices: Create for invoice drafts. The levels and categories per permission apply as in the dashboard: invoices and credit notes only appear as far as Invoices: View reaches (own, the categories selected there, or all). If the role works in certain categories exclusively, that limit applies here too.

An invoice draft can be created in a document category with documentCategoryId. prepare_invoice_draft lists in documentCategories the categories the user may select and shows the selected category for confirmation. Without it the draft has no category; the customer's default category is not prefilled. If the role works in certain categories exclusively, one of them is required unless Documents without a category is part of the limit.

Webhooks

Enterprise customers manage webhooks through /api/v1/webhooks with suitable scopes. There is no dashboard webhook editor. Consult the API explorer for events, signatures, test delivery and secret rotation. Receivers must deduplicate events by ID.

Open topic in help

Team management

Invite team members and assign roles.

Invitation:

  1. Go to Team
  2. Enter the email address
  3. Select a role
  4. Click Invite

The recipient receives an email with a registration link.

Manage roles:

  • Owner: cannot be removed; the role cannot be changed or assigned
  • Roles are assigned by anyone holding Assign roles and remove members (by default owners and admins): a standard role or, from the Professional plan, a custom role
  • Members cannot change their own role
  • What a role may do is set under Settings → Roles & permissions

Pending invitations:

Invitations that have not yet been accepted already count towards your plan’s user limit.

Open topic in help

Roles and permissions

Claribill uses role-based access control (RBAC). The five standard roles are the starting point; the overview shows their defaults. Under Settings → Roles & permissions you adjust the permissions of every role except the owner and, from the Professional plan, create custom roles. Where this documentation names roles, for example “owners and admins”, it refers to the default permissions.

Roles:

RoleDescription
OwnerCompany founder, always has every permission
Administrator (admin for short)Manages the company, the team and all documents
Accounting (“finance users” in this documentation)Invoicing and finances
EmployeeCreates invoices, maintains customers, edits their own documents
ExternalRead access to shared documents, for example for your tax adviser

Permission matrix (defaults):

AreaOwnerAdministratorAccountingEmployeeExternal
Dashboard✓✓✓✓✓
Invoices✓✓✓limitedshared only
Quotes✓✓✓read onlyread only
Order confirmations✓✓✓read onlyread only
Orders✓✓✓read onlyread only
Delivery notes✓✓✓read onlyread only
Credit notes✓✓✓✗✗
Customers✓✓✓limited✗
Items & services✓✓✓✗✗
Reports✓✓✓✗✗
Documents✓✓✓read onlyread only
Recurring✓✓✓read onlyread only
Exports✓✓✓✗✓
Team✓✓✗✗✗
Company settings✓✓accounting accounts only✗✗
API keys✓✓✗✗✗
Audit log✓✓✗✗✗
Email templates✓✓✗✗✗

Details:

  • Employees can by default create their own invoices, finalise their own drafts and cancel their own invoices. For other users' invoices they are limited to reading. By default only owners, admins and finance users can record payments
  • Customers: employees can view, create and edit customers by default, but cannot delete or archive them. External members have no access by default. Adjust each role's permissions under Settings → Roles & permissions
  • External: intended for tax advisers, by default with read access to shared invoices, quotes, order confirmations, orders, delivery notes, recurring invoices and documents, plus exports. No access to credit notes or customers. Available from the Professional plan
  • Owner: always has every permission, cannot be removed and the role cannot be changed
  • Custom roles (from the Professional plan): start with the permissions of a standard role as a template and can then be adjusted freely
  • Each user sees only the menu items they are permitted to access

Reading is not editing

Access to a section does not allow every action. By default only owners, admins and finance users create or manage quotes, confirmations, orders, delivery notes and recurring schedules. Employees and external users only read visible documents where section access allows it. By default finance users, employees and external users see only their own documents and those shared with them. They see more when the View permission of the document type is set to Categories (with the document categories selected for that permission) or All. All permissions are configurable per company under Settings → Roles & permissions; the section “Roles & permissions” describes the levels None / Own / Categories / All. Personal language, security and notification preferences differ from company administration.

Open topic in help

Team sharing

Anyone holding Manage document shares (by default owners and admins) can share visible individual documents with selected users. The Team page also supports sharing all documents created by a particular user or source role. Only members who can see all of the company’s documents can create such shares; otherwise the Team page hides both forms and states the reason.

A role-based share gives one selected recipient access to documents created by members of the chosen source role. It does not automatically grant all members of a role access to every document.

Sharing extends document visibility but does not grant additional permissions to create, record payments, send or administer. It works for members whose View permission of the document type is set to Own or Categories; at None even a shared document stays hidden, and at All no sharing is needed. The limit This role works in certain categories exclusively still applies: a shared document outside the limit stays locked. By default finance users, employees and external users see only their own and shared documents.

Open topic in help

Switch companies

The company selector in the header appears once you belong to at least two companies. Selecting a company opens its dashboard. With one membership, only the company name is shown.

Create new company in the selector opens onboarding. If the selector is absent because there is only one membership, eligible users can open /en/onboarding directly. Owned-company limits are Free and Starter 1, Professional 3, Enterprise 10.

Documents, templates, subscriptions and roles are separate for each company. Other open tabs display a company-change reload notice. Reload before continuing; stale forms cannot save into the newly active company.

Open topic in help

AI assistant

The AI assistant handles in a chat what you otherwise do in the dashboard. Describe in your own words what needs to be done. The assistant creates the documents and carries out the tasks.

Where to find it

  • AI assistant in the sidebar: full-screen chat with conversation history and activity log
  • Ctrl/⌘ + J on any dashboard page: opens the chat on the right. The assistant knows which document you are looking at.

What it can do

  • Create invoices, pro formas, quotes, order confirmations, delivery notes, orders, credit notes and recurring invoices
  • Convert quotes and order confirmations into invoices
  • Finalize and send invoices, record payments, send reminders, cancel invoices
  • Find, create and update customers and products
  • Figures: open and overdue invoices, revenue of the month and year

Examples:

  • “Create an invoice for Müller GmbH for 10 consulting hours at €120 for September.”
  • “Convert quote AN-2026-0042 into an invoice and send it to the customer.”
  • “Set up a monthly recurring invoice for Huber for the maintenance fee.”
  • “Which invoices are overdue?”

Confirmation before anything leaves the app

The assistant looks things up and creates drafts right away. Anything with an external effect or without a way back first appears as a confirmation card with all details (recipient, amount, invoice number):

  • Sending by email
  • Finalizing with an invoice number
  • Payments and reminders
  • Cancelling and deleting
  • Status changes and activating a recurring invoice
  • Changes to existing customers and products

Only Confirm and run carries out the action exactly as shown. A proposal expires with your next message or after 30 minutes. The assistant always creates recurring invoices paused and without automatic sending.

Activity log and conversations

  • On the right, the activity log shows what the assistant looked up, decided, created or sent, each with a link to the document.
  • Under History you open, search, rename and delete earlier conversations.
  • Conversations are private: even colleagues in the same company cannot see them.

Document categories

Name the category when creating a document (“… in the category Project A”) and it is created there: invoices, pro formas, quotes, delivery notes, orders, free credit notes and recurring invoices. You can select the same categories as in the dashboard form. Without a category the document stays uncategorized; the assistant does not apply a customer's default category on its own. It changes the category of a draft invoice if your role may Assign a category to documents for that invoice.

Permissions

  • The assistant is available to roles with the permission Use the AI assistant (Settings → Roles & permissions). By default these are all roles except External (tax advisers).
  • The assistant can only do what your role may do in the dashboard, with the same levels and categories per permission. It sees and changes documents as far as the respective permission reaches (Own, Categories or All); “Invoices: View” can cover other categories than “Invoices: Edit”. With the default permissions, employees do not create quotes or record payments, for example; this can be changed per role under Settings → Roles & permissions.
  • If your role works in certain categories exclusively, that limit also applies in the chat: the assistant does not find documents outside it, and new documents need one of these categories.
  • The assistant knows your permissions and tells you up front when a task is outside them.
  • Owners and admins turn it on or off for the whole company under Settings → AI assistant.

AI credits

Every request uses AI credits:

RequestCredits
Question without lookups1
With lookups2
With changes3
Confirming a card0

The monthly allowance depends on the plan: Free 50, Starter 300, Professional 1,500, Enterprise 5,000. The current usage is shown in the chat and under Settings → AI assistant.

Open topic in help

Files and privacy

Attaching files

Use the paper clip in the chat to attach files, for example a customer order that should become a quote.

  • PDF, PNG, JPEG and WebP are allowed, up to 3 files and at most 3 MB per message in total.
  • The assistant takes over the customer, items, quantities and prices and matches them with your customers and products.
  • After an attachment the assistant shows a confirmation card for every write action, drafts included. It treats content from files as external data, not as instructions.

Storage in the document archive

Claribill stores attached files under Documents in the AI assistant folder, with one subfolder per conversation. Your plan's storage allowance and the usual document visibility rules apply.

Deleting

When you delete a conversation in the history, Claribill also removes its folder and all files in it. Conversations without a new message are deleted automatically after 365 days. Documents the assistant created (invoices, quotes …) are kept.

What data is sent to the AI model

To answer, Claribill sends your message, the required customer and document data and attached files to Anthropic (Claude) via the Vercel AI Gateway. Customer email addresses are only passed on masked.

Open topic in help

Plan & Billing

Claribill offers four plans. New companies receive a 14-day trial with Professional features during setup. A purchased paid plan determines the features available thereafter.

Free

  • One user, one company
  • 25 customers, 50 documents per year: invoices, credit notes and proformas count from finalisation, quotes, order confirmations and delivery notes from Sent, and orders from Active; all count together, while drafts do not count
  • 25 emails per month, 1 GB storage
  • AI assistant with 50 AI credits per month
  • Claribill branding is required on PDFs and emails
  • No CSV import, DATEV export or team invitations

Starter – €19/month (€190/year)

  • Three users, one company
  • 500 customers, 1,000 documents per year, 5 GB storage, 150 emails per month, 10,000 API calls per month
  • AI assistant with 300 AI credits per month
  • Claribill branding remains on PDFs and emails, as on the Free plan
  • Team invitations and roles with adjustable permissions, CSV import, DATEV export
  • REST API access
  • Recurring invoices
  • Email support

Professional – €29/month (€290/year)

  • Ten users, three companies
  • 2,000 customers, 2,500 documents per year, 25 GB storage, 1,000 emails per month, 50,000 API calls per month
  • AI assistant with 1,500 AI credits per month
  • No Claribill branding on PDFs or emails
  • External access for tax advisers using the External role
  • Custom roles in addition to the five standard roles
  • Custom email domain and SMTP server
  • Bank integration through finAPI
  • Priority support

Enterprise – €99/month (€990/year)

  • 25 users as a baseline, ten companies
  • 10,000 customers, 10,000 documents per year, 150 GB storage, 3,000 emails per month, 250,000 API calls per month
  • AI assistant with 5,000 AI credits per month
  • Everything included in Professional
  • Webhooks, available only on this plan
  • Highest support priority

View your plan:

Settings → Plan & Billing shows your current plan and usage against its limits.

Change the recipient of Claribill subscription invoices

  1. Open Settings → Plan & Billing → Billing recipient. If your company address is missing, Edit company details opens the details used on your own documents.
  2. As an owner or admin, enable Invoice a different company. Complete Company name, Street and number, Postcode, City, Country and Billing email. Contact person and VAT ID are optional.
  3. Select Save billing recipient. This applies to future subscription invoices; it does not change the sender on your customer documents.
  4. To return to your company details, turn off Invoice a different company and select Save change. If an existing recipient is suggested, Apply from Stripe fills in the form. Check the details before saving.

Paid plan prices are listed plus VAT. Use Monthly or Yearly to select the billing interval.

Open topic in help

Branding rules

Branding depends on your subscription plan.

Free and Starter plans: branding enabled

On PDFs:

  • Claribill logo at the bottom of the page
  • A note that the document was created with Claribill's free invoicing software
  • A QR code linking to the Claribill website

In emails:

  • Claribill logo in the footer
  • “Created with Claribill · Invoicing software for the self-employed”
  • A link to the Claribill website

Every document email also includes the neutral “Sent via Claribill” notice, regardless of plan. This security notice is separate from advertising badges and remains with custom email designs.

Professional and above

  • No branding on PDFs
  • No branding in emails
  • Documents use your own company branding, apart from the neutral sending notice

Optional badge:

On paid plans, you can voluntarily enable Show Claribill badge on documents under Settings → Brand colours to support Claribill.

Upgrade:

Owners and admins can choose a plan and billing interval in subscription settings and continue to checkout. Use the customer portal there to manage an existing subscription.

Open topic in help