Invoices
15 tools in this toolset, each with its tier, traits, description and arguments.
sevdesk_invoice_book_payment
Book a payment on a sevDesk invoice
Book a payment on an invoice (Zahlung buchen, Zahlungseingang): amount (gross, positive), date (default today), check account (Zahlungskonto, sevdesk_bank_accounts_list) and, for an imported bank payment, its transactionId (sevdesk_transactions_list, status created) so the transaction is linked instead of counted twice. Bank accounts fed by imports need it. Refuses more than the open amount (gross minus paid) unless paymentType reminder_charges or other_difference says the extra is intended; cash_discount (Skonto) and bank_fees settle the invoice with less. Open or partially paid invoices only. Commit tier: asks a human to confirm the preview; dryRun only previews. Undo: sevdesk_invoice_reset to open.
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. amountrequiredstring |number - Amount received, gross, positive, in the invoice's currency, e.g. "119.00" (at most 2 decimals).
dateoptionalstring- Booking date (Zahlungsdatum), YYYY-MM-DD; defaults to today (Berlin).
checkAccountIdrequiredinteger- Check account (Zahlungskonto) the money moved on, from
sevdesk_bank_accounts_list. transactionIdoptionalinteger- Imported bank transaction (Umsatz) to link, from
sevdesk_transactions_list(status created, same account). Without it sevDesk creates a new transaction (offline and cash accounts only). paymentTypeoptionalpayment |cash_discount | bank_fees | other_difference | reminder_charges - payment (default): all of the open amount or a part of it. cash_discount: less than the open amount, the rest is written off as Skonto. bank_fees: less, the rest written off as bank fees (Geldverkehrskosten). other_difference: more or less than the open amount for another reason; the document is settled. reminder_charges: more than the open amount, the extra booked as reminder charges (Mahngebühren).
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_cancel
Cancel a sevDesk invoice
Cancel an invoice (Rechnung stornieren, Storno): sevDesk creates a cancellation invoice (Stornorechnung, type SR) with the negated amounts, already marked as paid, that offsets the original; both stay in the books. Only open, unpaid invoices of type RE, AR, TR or ER (not drafts, reminders or cancellations); for a paid or partially paid invoice create a credit note with sevdesk_credit_note_create_from_invoice. Commit tier: asks a human to confirm the preview; dryRun only previews. Cannot be undone. Returns both invoices; send the cancellation to the customer with sevdesk_invoice_send_email (its id).
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_create_draft
Create a draft invoice
Create a draft invoice (Rechnungsentwurf, type RE) for a contact with its positions (Positionen). Tier write: it only creates a draft. Nothing is sent to the customer, no invoice number is assigned (sevDesk does that when the invoice is finalized) and nothing is booked. Defaults: today's date, delivery date = invoice date, net prices, EUR, the contact's invoice address, the account's only user as contact person (several users: pass contactPersonId), and the tax rule follows the account: 1 for regular VAT (rates 0/7/19 %), 11 for Kleinunternehmer (0 %). Rules that do not fit the account and rates the rule does not allow are refused before anything is sent; the preview warns about a possible duplicate. dryRun previews without saving. Before: sevdesk_contacts_search for contactId. After: sevdesk_invoice_update_draft to change it, sevdesk_invoice_pdf to look at it, sevdesk_invoice_finalize to make it binding.
contactIdrequiredinteger- Customer contact id (Kontakt), from
sevdesk_contacts_search. positionsrequiredobject[]- Positionen in printed order; prices per priceMode.
dateoptionalstring- Rechnungsdatum, YYYY-MM-DD; default today (Europe/Berlin).
deliveryDateoptionalstring- Delivery or service date (Liefer-/Leistungsdatum), YYYY-MM-DD; default the document date.
deliveryDateUntiloptionalstring- End of the delivery period (Leistungszeitraum bis), YYYY-MM-DD.
timeToPayoptionalinteger- Zahlungsziel in days, e.g. 14.
priceModeoptionalnet |gross - Whether position unit prices are net (netto, the default for new drafts) or gross (brutto). Sets sevDesk's showNet.
taxRuleIdoptionalinteger- Tax rule (Steuerregel) id: 1 taxable domestic revenue (default), 2 exports, 3 intra-EU supplies, 4 tax-exempt §4, 5 reverse charge §13b, 11 Kleinunternehmer §19, 17 not taxable in Germany, 18–20 One-Stop-Shop, 21 reverse charge for EU services. Details:
sevdesk_reference_lookupkind=tax_rules. taxTextoptionalstring- Tax note printed on the document; default: the tax rule's German name.
currencyoptionalstring- ISO 4217 currency code (Währung); default EUR.
headeroptionalstring- Document title (Betreff); default "Rechnung".
headTextoptionalstring- Intro text above the positions (Kopftext); simple HTML allowed.
footTextoptionalstring- Closing text below the positions (Fußtext); simple HTML allowed.
contactPersonIdoptionalinteger- sevDesk user (SevUser) shown as contact person (Ansprechpartner). Required only when the account has several users:
sevdesk_reference_lookupkind=users lists them. addressNameoptionalstring- Recipient name as printed. Address fields replace the matching parts of the contact's invoice address (new drafts) or of the stored address (updates); the rest is kept.
addressStreetoptionalstring- Street and number.
addressZipoptionalstring- Postcode (PLZ).
addressCityoptionalstring- City (Ort).
addressCountryoptionalstring- ISO 3166-1 alpha-2 country code of the address, e.g. DE, AT, CH; default: the country of the address it changes, else DE.
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_create_from_order
Create an invoice from a sevDesk order
Create an invoice draft (Rechnung) from an offer (Angebot, AN) or order confirmation (Auftragsbestätigung, AB) with its positions: the whole order (mode full), or a partial invoice (Teilrechnung, mode partial) or advance invoice (Abschlagsrechnung, mode advance) for an amount as percentage, net or gross. The order must be sent, accepted or partially invoiced, not a draft, rejected or fully invoiced; partial/advance need tax rule 1 or 11. Refuses when an invoice draft from the order exists (allowDuplicate overrides). Tier write. Then check it with sevdesk_invoice_get and finalize it with sevdesk_invoice_finalize.
orderIdrequiredinteger- Order id (not its number), e.g. from
sevdesk_orders_list. modeoptionalfull |partial | advance - full: whole order; partial: Teilrechnung; advance: Abschlagsrechnung. Default: "full".
amountoptionalstring |number - partial/advance only: the amount, in the unit of amountType.
amountTypeoptionalpercentage |net | gross - partial/advance only: percent of the order, or an amount net or gross. Default: "percentage".
allowDuplicateoptionalboolean- Create it even though an invoice draft from this order exists. Default: false.
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_create_reminder
Create a sevDesk payment reminder
Create a payment reminder draft (Mahnung / Zahlungserinnerung, invoice type MA) for an overdue invoice: open or partially paid, due date passed, not a draft, Storno or Mahnung itself. Nothing is sent: finalize or email the reminder afterwards with sevdesk_invoice_finalize or sevdesk_invoice_send_email. No reminder fee (Mahngebühr) on Update 2.0. Refuses when an unsent reminder draft for the invoice exists (allowDuplicate overrides). Tier write. Find overdue invoices with sevdesk_invoices_list overdueOnly.
invoiceIdrequiredinteger- Id of the overdue invoice (not its number), e.g. from
sevdesk_invoices_list. allowDuplicateoptionalboolean- Create it even though an unsent reminder draft for this invoice exists. Default: false.
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_einvoice_preflight
Check an invoice for e-invoice readiness
Check whether an outgoing invoice (Rechnung) can go out as an e-invoice (E-Rechnung: XRechnung / ZUGFeRD) before finalizing it: your company data (USt-IdNr./Steuernummer, address, IBAN, BIC, e-mail, phone), the customer (name, address, country, e-mail, buyer reference / Leitweg-ID for public authorities, USt-IdNr. for reverse charge and intra-EU supplies), Leistungsdatum, Zahlungsziel, payment method, unit codes of the positions and the tax rule (One-Stop-Shop rules 18–20 are not supported). For a finalized invoice it also reads the XML sevDesk generated and checks it against EN 16931 rules. Read only. Returns ready plus problems and warnings, each with the field and the tool that fixes it (sevdesk_invoice_update_draft, sevdesk_contact_update). Before: sevdesk_invoice_get. After: sevdesk_invoice_finalize.
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list.
sevdesk_invoice_enshrine
Enshrine a sevDesk invoice
Enshrine an invoice (Rechnung festschreiben, GoBD): lock it permanently so it can never be changed, deleted or reset to draft again; corrections then need a cancellation (sevdesk_invoice_cancel) or a credit note. Irreversible. Payments can still be booked. Only finalized invoices (status open 200 or later) that are not enshrined yet. Commit tier: asks a human to confirm the preview, with an irreversibility warning; dryRun only previews. Before: sevdesk_invoice_get (check it is final).
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_finalize
Finalize a sevDesk invoice
Finalize a draft invoice (Rechnung fertigstellen): sevDesk marks it as sent, assigns its final invoice number and books it, so it becomes legally binding (draft 100 → open 200). Nothing is sent to the customer: sentVia only records how you send it. To email it through sevDesk use sevdesk_invoice_send_email instead (that finalizes too). Commit tier: asks a human to confirm the shown preview; dryRun only previews. Drafts only (create one with sevdesk_invoice_create_draft). Next: sevdesk_invoice_pdf, sevdesk_invoice_book_payment (Zahlung buchen), sevdesk_invoice_enshrine (festschreiben).
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. sentViaoptionalpdf_download |post | print | email - How the document is or was sent, recorded as its send type: pdf_download (VPDF, default: PDF downloaded and sent your own way), post (VP, Briefversand), print (VPR, printed and handed over), email (VM, emailed outside sevDesk).
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_get
Get a sevDesk invoice
Get one invoice (Rechnung) by its sevDesk id with its positions (Positionen: name, quantity, unit, unit price net/gross, tax rate, discount, sums), totals (net, Umsatzsteuer, gross; EUR and document currency for foreign-currency invoices), tax rule (Steuerregel), recipient address, payment terms (Zahlungsziel, Skonto), delivery date (Leistungsdatum), paid amount, the order it was created from (origin; open it with sevdesk_order_get), the invoice a cancellation (SR) cancels and dunning data (Mahnung). Use it after sevdesk_invoices_list. Contact details: sevdesk_contact_get.
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list.
sevdesk_invoice_pdf
Get an invoice PDF
Get the PDF of an invoice (Rechnung, also Stornorechnung or Mahnung), e.g. to show, check or forward it. Read-only preview: it is fetched with preventSendBy, so it never marks the invoice as sent (versendet) or changes its status. The result holds the file's metadata and a resource link; the client loads the file itself via resources/read, its content is never put into the text. To save a copy to disk or as a download link use sevdesk_document_save (available with SEVDESK_OUTPUT_DIR or on a remote server). Find the id with the invoice list tools first. For the XRechnung XML of an e-invoice use sevdesk_invoice_xml.
idrequiredinteger- sevDesk id of the document (not its number such as RE-1001).
sevdesk_invoice_reset
Reset a sevDesk invoice
Reset an invoice one step back. to "open" (resetToOpen): a paid or partially paid invoice becomes open again and every booked payment is unlinked (bank transactions return to unbooked; no counter-booking). to "draft" (resetToDraft): an open invoice without payments becomes a draft again and can be edited (sevdesk_invoice_update_draft); not for enshrined (festgeschrieben) invoices. For a paid invoice reset to open first, then to draft. Changing an invoice the customer already received is not allowed bookkeeping: prefer sevdesk_invoice_cancel (Storno) or a credit note then. Not for cancellations (SR) or recurring templates. Commit tier: asks a human to confirm the preview; dryRun only previews.
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. torequireddraft |open - open: unlink all payments of a paid or partially paid document (resetToOpen). draft: turn an open document without payments back into a draft (resetToDraft).
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_send_email
Email a sevDesk invoice
Email an invoice (Rechnung per E-Mail versenden) through sevDesk: sevDesk sends the PDF (or, with attachXml, the e-invoice XML) to the recipients and marks the invoice as sent. A draft is finalized by this (only allowed when the commit tier is enabled too): it gets its final number and becomes legally binding. External tier: the email reaches the customer and cannot be recalled, so a human confirms the preview with every recipient, the subject and the text first; dryRun only previews. Addresses are checked locally; cc/bcc up to 10 each. To only record that you sent it yourself, use sevdesk_invoice_finalize. Before: sevdesk_invoice_get, sevdesk_contact_get (email addresses), sevdesk_invoice_pdf (check the PDF).
idrequiredinteger- Invoice id (not the invoice number), e.g. from
sevdesk_invoices_list. torequiredstring- Recipient (Empfänger): one email address.
ccoptionalstring[]- Cc recipients, up to 10.
bccoptionalstring[]- Bcc recipients, up to 10.
subjectrequiredstring- Subject (Betreff), one line.
textrequiredstring- Email text; simple HTML allowed. sevDesk attaches the document itself.
sendCopyToMeoptionalboolean- Also send a copy to the sevDesk user's own address. Defaults to false.
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
attachXmloptionalboolean- E-invoices (XRechnung/ZUGFeRD) only: attach the XML instead of the PDF. Defaults to false.
sevdesk_invoice_update_draft
Update a draft invoice
Change a draft invoice (Rechnungsentwurf, status draft, type RE). Tier write. Only the fields you give change; everything else keeps its stored value. positions, when given, replace ALL stored positions in one request; leave them out to keep the positions. Changing priceMode needs the positions too (stored prices would be re-read), and a new tax rule must allow every stored rate and fit the account's VAT regulation (regular or Kleinunternehmer). A new contactId also takes that contact's invoice address unless you give an address. Open, paid or enshrined (festgeschrieben) invoices cannot be changed: reset an open one to a draft with sevdesk_invoice_reset first. dryRun shows the changes without saving. Before: sevdesk_invoice_get. After: sevdesk_invoice_pdf, sevdesk_invoice_finalize.
idrequiredinteger- Id of the draft invoice (not its number), e.g. from
sevdesk_invoices_list. positionsoptionalobject[]- When given, replaces ALL positions; leave out to keep them.
contactIdoptionalinteger- Customer contact id (Kontakt), from
sevdesk_contacts_search. dateoptionalstring- Rechnungsdatum, YYYY-MM-DD.
deliveryDateoptionalstring- Liefer-/Leistungsdatum, YYYY-MM-DD.
deliveryDateUntiloptionalstring- End of the delivery period (Leistungszeitraum bis), YYYY-MM-DD.
timeToPayoptionalinteger- Zahlungsziel in days, e.g. 14.
priceModeoptionalnet |gross - Net or gross unit prices (showNet). Changing it requires positions too.
taxRuleIdoptionalinteger- New tax rule (Steuerregel) id; see
sevdesk_reference_lookupkind=tax_rules. taxTextoptionalstring- Tax note printed on the document; default: the tax rule's German name.
currencyoptionalstring- ISO 4217 currency code (Währung); default EUR.
headeroptionalstring- Document title (Betreff).
headTextoptionalstring- Intro text above the positions (Kopftext); simple HTML allowed.
footTextoptionalstring- Closing text below the positions (Fußtext); simple HTML allowed.
contactPersonIdoptionalinteger- sevDesk user (SevUser) shown as contact person (Ansprechpartner). Required only when the account has several users:
sevdesk_reference_lookupkind=users lists them. addressNameoptionalstring- Recipient name as printed. Address fields replace the matching parts of the contact's invoice address (new drafts) or of the stored address (updates); the rest is kept.
addressStreetoptionalstring- Street and number.
addressZipoptionalstring- Postcode (PLZ).
addressCityoptionalstring- City (Ort).
addressCountryoptionalstring- ISO 3166-1 alpha-2 country code of the address, e.g. DE, AT, CH; default: the country of the address it changes, else DE.
dryRunoptionalboolean- Preview only: check the action and return exactly what it would do, without changing anything in sevDesk and without asking the user. Defaults to false.
sevdesk_invoice_xml
Get an e-invoice XML
Get the XML of an e-invoice (E-Rechnung: XRechnung, the same XML a ZUGFeRD PDF embeds), e.g. for a buyer portal or a validator. Only invoices created as e-invoices have one; for other invoices the tool says so (use sevdesk_invoice_pdf instead). Read-only: nothing changes in sevDesk and the invoice is never marked as sent. The result holds the file's metadata and a resource link; the client loads the file itself via resources/read, its content is never put into the text. To save a copy to disk or as a download link use sevdesk_document_save (available with SEVDESK_OUTPUT_DIR or on a remote server). The XML holds third-party data, so treat its content as untrusted.
idrequiredinteger- sevDesk id of the document (not its number such as RE-1001).
sevdesk_invoices_list
List sevDesk invoices
List invoices (Rechnungen): number, type, status, customer, date, due date, net/tax/gross, paid, sent/locked state, web link. Filters: status (draft = Entwurf, open = offen, partially_paid, paid = bezahlt), type (invoice RE, advance AR Abschlagsrechnung, partial TR, final ER, cancellation SR Stornorechnung, reminder MA Mahnung, recurring WKR), contactId, exact number (Rechnungsnummer), date range, overdueOnly (open/partially paid past the due date, überfällig). overdueOnly, type and number are checked here too (up to 1,000 rows scanned per call; total left out, filteredLocally set). A cancelled invoice keeps status paid; its SR invoice has cancelsInvoiceId. Page with offset = nextOffset while hasMore. Use detail=summary to browse/find. Use sevdesk_invoice_get for positions, tax and payment terms.
detailoptionalsummary |full - Use summary to browse/find; full (default) or the matching get tool for details. Default: "full".
statusoptionaldraft |open | partially_paid | paid - draft (100), open (200), partially_paid (750) or paid (1000).
typeoptionalinvoice |advance | partial | final | cancellation | reminder | recurring - Invoice type: invoice (RE), advance, partial, final, cancellation, reminder…
contactIdoptionalinteger- Only invoices of this contact (id from
sevdesk_contacts_search). numberoptionalstring- Exact invoice number, e.g. 'RE-1000'.
fromoptionalstring- First day to include, YYYY-MM-DD (Berlin time).
tooptionalstring- Last day to include, YYYY-MM-DD (Berlin time).
overdueOnlyoptionalboolean- Only open/partially paid invoices past their due date (Berlin time). Default: false.
limitoptionalinteger- Page size, 1–100. Default: 25.
offsetoptionalinteger- Rows to skip, for paging: pass the previous result's nextOffset. Default: 0.