Credit notes
10 tools in this toolset, each with its tier, traits, description and arguments.
sevdesk_credit_note_book_payment
Book a payment on a sevDesk credit note
Book a payout on a credit note (Gutschrift auszahlen, Zahlungsausgang): amount (gross, positive; sent to sevDesk as money out), 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 unless paymentType other_difference says the extra is intended. Open credit notes only (sevDesk reports no paid amount for partially paid ones). Commit tier: asks a human to confirm the preview; dryRun only previews. Undo: sevdesk_credit_note_reset to open.
idrequiredinteger- Credit note id (not the credit note number), e.g. from
sevdesk_credit_notes_list. amountrequiredstring |number - Amount paid out, gross, positive, in the credit note'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 - 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.
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_credit_note_create_draft
Create a draft credit note
Create a draft credit note (Gutschrift) for a contact with its positions. Tier write: it only creates a draft; nothing is sent or booked. Saving reserves the next number of sevDesk's number range (shown in the preview). bookingCategory is required: underachievement (Minderleistung) reduces a finalized invoice of the same contact given as sourceInvoiceId (not cancelled; refused when a credit note for it exists unless allowDuplicate), and every rate must be one of that invoice's rates; provision (Provisionsgutschrift) uses tax rule 9; royalty_assigned/_unassigned (Lizenzen) are not verified live yet. To credit a whole invoice use sevdesk_credit_note_create_from_invoice instead. Defaults: today, net prices, EUR (or the invoice's currency), the contact's invoice address, the account's only user as contact person, tax rule 1 (11 on a Kleinunternehmer account). dryRun previews without saving. After: sevdesk_credit_note_pdf, sevdesk_credit_note_finalize.
contactIdrequiredinteger- Customer contact id (Kontakt), from
sevdesk_contacts_search. bookingCategoryrequiredunderachievement |provision | royalty_assigned | royalty_unassigned - Buchungskategorie: underachievement (Minderleistung: reduces an issued invoice, needs sourceInvoiceId), provision (Provisionsgutschrift, tax rule 9), royalty_assigned or royalty_unassigned (Lizenzgebühren).
sourceInvoiceIdoptionalinteger- underachievement only: id of the finalized invoice this credit note reduces (refSrcInvoice).
allowDuplicateoptionalboolean- underachievement only: create it even though a credit note for the source invoice exists (e.g. a second partial refund). Default false.
positionsrequiredobject[]- Positionen in printed order; prices per priceMode.
dateoptionalstring- Gutschriftsdatum, 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.
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. Default: the source invoice's rule (underachievement), 9 (provision; 10 on a Kleinunternehmer account) or the account's: 1 for regular VAT, 11 for Kleinunternehmer. See
sevdesk_reference_lookupkind=tax_rules. taxTextoptionalstring- Tax note printed on the document; default: the tax rule's German name.
currencyoptionalstring- ISO 4217 code; default EUR or the source invoice's currency.
headeroptionalstring- Document title (Betreff); default "Gutschrift".
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_credit_note_create_from_invoice
Create a credit note from a sevDesk invoice
Create a credit note draft (Gutschrift / Rechnungskorrektur) from a finalized invoice (open, partially paid or paid; not a draft, Storno, Mahnung or Abo template, and not cancelled) with all its positions: the way to correct or refund a paid invoice. For an unpaid invoice that should be voided completely, cancel it instead (sevdesk_invoice_cancel). Refuses when a credit note for the invoice exists (allowDuplicate overrides, e.g. a second partial refund). Tier write. Afterwards sevDesk's credit note counter is moved past the new draft's number (sevDesk does not do that itself). Then check it with sevdesk_credit_note_get and finalize it with sevdesk_credit_note_finalize.
invoiceIdrequiredinteger- Invoice id (not its number), e.g. from
sevdesk_invoices_list. allowDuplicateoptionalboolean- Create it even though a credit note from 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_credit_note_enshrine
Enshrine a sevDesk credit note
Enshrine a credit note (Gutschrift festschreiben, GoBD): lock it permanently so it can never be reset to draft or deleted again. Irreversible. Payments can still be booked. Only finalized credit notes (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_credit_note_get (check it is final).
idrequiredinteger- Credit note id (not the credit note number), e.g. from
sevdesk_credit_notes_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_credit_note_finalize
Finalize a sevDesk credit note
Finalize a draft credit note (Gutschrift fertigstellen): sevDesk marks it as sent and books it (draft 100 → open 200) under the number the draft carries. Nothing is sent to the customer: sentVia only records how you send it. To email it through sevDesk use sevdesk_credit_note_send_email instead. Commit tier: asks a human to confirm the shown preview; dryRun only previews. Drafts with a number only (sevDesk can fail half-way on a draft without one; sevdesk_credit_note_create_draft assigns one). Next: sevdesk_credit_note_book_payment (Auszahlung buchen), sevdesk_credit_note_enshrine.
idrequiredinteger- Credit note id (not the credit note number), e.g. from
sevdesk_credit_notes_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_credit_note_get
Get a sevDesk credit note
Get one credit note (Gutschrift) by its sevDesk id with its positions (name, quantity, unit, unit price net/gross, tax rate, sums), totals (net, Umsatzsteuer, gross), tax rule (Steuerregel), booking category, the invoice or voucher it refers to (sourceInvoiceId, sourceVoucherId), recipient address and delivery date. Use it after sevdesk_credit_notes_list; open the source invoice with sevdesk_invoice_get.
idrequiredinteger- Credit note id (not its number), e.g. from
sevdesk_credit_notes_list.
sevdesk_credit_note_pdf
Get a credit note PDF
Get the PDF of a credit note (Gutschrift), e.g. to show, check or forward it. Read-only preview: it is fetched with preventSendBy, so it never marks the credit note 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 credit note list tools first.
idrequiredinteger- sevDesk id of the document (not its number such as RE-1001).
sevdesk_credit_note_reset
Reset a sevDesk credit note
Reset a credit note one step back. to "open" (resetToOpen): a paid or partially paid credit note becomes open again and every booked payout is unlinked (bank transactions return to unbooked; no counter-booking). to "draft" (resetToDraft): an open credit note without payouts becomes a draft again; not for enshrined (festgeschrieben) credit notes. For a paid credit note reset to open first, then to draft. Commit tier: asks a human to confirm the preview; dryRun only previews.
idrequiredinteger- Credit note id (not the credit note number), e.g. from
sevdesk_credit_notes_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_credit_note_send_email
Email a sevDesk credit note
Email a credit note (Gutschrift per E-Mail versenden) through sevDesk: sevDesk sends the PDF to the recipients and marks the credit note as sent; a draft is finalized by this and gets its final number (only allowed when the commit tier is enabled too). 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_credit_note_finalize. Before: sevdesk_credit_note_get, sevdesk_contact_get, sevdesk_credit_note_pdf.
idrequiredinteger- Credit note id (not the credit note number), e.g. from
sevdesk_credit_notes_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.
sevdesk_credit_notes_list
List sevDesk credit notes
List credit notes (Gutschriften) with compact rows: number, status, contact, date, net/tax/gross, booking category (e.g. UNDERACHIEVEMENT = Minderleistung, PROVISION) and the invoice they refer to (sourceInvoiceId). Filter by status (draft = Entwurf, open, partially_paid, paid), contactId, exact credit note number (Gutschriftsnummer) and date range. Page with offset = nextOffset while hasMore. Use detail=summary to browse/find. Use sevdesk_credit_note_get for details and positions. The source invoice: sevdesk_invoice_get.
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).
contactIdoptionalinteger- Only credit notes of this contact.
numberoptionalstring- Exact credit note number, e.g. 'GU-1000'.
fromoptionalstring- First day to include, YYYY-MM-DD (Berlin time).
tooptionalstring- Last day to include, YYYY-MM-DD (Berlin time).
limitoptionalinteger- Page size, 1–100. Default: 25.
offsetoptionalinteger- Rows to skip, for paging: pass the previous result's nextOffset. Default: 0.