Draft a credit note of an issued invoice (tenant:trade:sales:write)
POST /api/trade/v1/sales/invoices/{id}/credit-notes
Module: Trade · operationId: draftCreditNote · Tag: Transactions · Auth: access token (Authorization: Bearer <accessToken>)
Creates a DRAFT credit note (placeholder number, issued with issueInvoiceDraft as GS-<year>-<nnnnn>, XRechnung
type 381 naming the invoice) of an ISSUED invoice: the given invoice lines and quantities, or without lines
whatever is not credited yet. A line is never credited beyond its invoiced quantity minus what other credit notes
(drafts included) credit. With returnToStock the articles are booked back into stock when it is issued – only for an
invoice made of delivery notes that booked them out of stock (422 for a drop shipment, an order-direct or a
hand-made invoice).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json
footerText(string)headerText(string)lines(array of object)invoiceLineId(string (uuid), required)quantity(number, required)
returnToStock(boolean): Book the credited articles back into stock when the credit note is issued
Example:
{
"headerText": "Gutschrift für einen nicht benötigten Access Point (Rücknahme).",
"lines": [
{
"invoiceLineId": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
"quantity": 1
}
],
"returnToStock": true
}
Responses
- 201 The transaction (
application/json) - 400 Error (
application/json) - 401 No valid session or bearer token (no body).
- 404 Not found in the tenant. (
application/json) - 409 The invoice is not issued, a line would be credited beyond its invoiced quantity, or everything is credited already (German text). (
application/json) - 422 A line is no line of the invoice, is named twice or has a negative quantity; or
returnToStockfor goods that never left stock (German text). (application/json) - 423 An active workflow locks the transaction. (
application/json)
Fields of the 201 answer:
addressId(string (uuid)): Masterdata address of the partner.createdAt(string (date-time), read-only): When the transaction was created.currency(string): ISO 4217; EUR when empty.customerNo(string, read-only): Customer number of the tenant.deliveryDate(string (date-time)): Delivery date.documentDate(string (date-time)): Today when empty on create.documentRefId(string (uuid)): DMS document of the transaction.dueDate(string (date-time)): Due date.eInvoiceValidation(object, read-only): The newest e-invoice check of the document (details:getInvoiceValidation). Set only for invoices and credit notes, only on reads (listTransactions,getTransaction), and absent when no check ran.error(string, read-only): Error of the last processing (e.g. of an inbound invoice).exchangeRate(number): 1 when empty.externalTransactionNumber(string): The other party's number: the supplier's invoice number (inbound invoices) or order confirmation number (purchase orders; only there it is written through this API).footerText(string): Text printed below the lines.frozenSnapshot(object, read-only): Evidence copy of an accepted offer; written once.grossTotal(number, read-only): Gross total, computed from the lines.headerText(string): Text printed above the lines.id(string (uuid), read-only): Id of the transaction.items(array of TransactionLine): Lines; on update they replace all lines when present.name(string, required): Name of the article or line.quantity(number, required): Quantity.articleNumber(string): Article number in masterdata.createdAt(string (date-time), read-only): When the line was created.description(string): Description of the line.discountPercent(number): Discount in percent.ean(string): EAN (GTIN) of the article.id(string (uuid), read-only): Id of the line.isOptional(boolean): The line is optional (position typeoptional).isSelected(boolean): Selected optional lines count in the totals.lineData(object): Facts of the line by type (e.g. serial numbers, sources).mpn(string): Manufacturer part number.parentItemId(string (uuid)): Line this line belongs to (e.g. a component of a bundle).positionNumber(integer, read-only): Set from the order ofitems.positionType(PositionType): Empty isnormal; the totals countnormallines and selectedoptionallines. (one ofnormal,optional,title,subtotal,text)predecessorLineId(string (uuid), read-only): The line of the previous version.productId(string (uuid)): Masterdata article (product) id.sortOrder(integer): Sort order (ascending).sourceLineId(string (uuid), read-only): Line this one was made from (order line of a delivery note or draft invoice, invoice line of a credit note). Set by the system; a value sent by a client is dropped.taxRate(number): Percent.totalPriceGross(number, read-only): Gross total of the line, computed.totalPriceNet(number, read-only): Net total of the line, computed.transactionId(string (uuid), read-only): Id of the transaction.unit(string): Unit of measure.unitPriceNet(number): Negative for a credit position.updatedAt(string (date-time), read-only): When the line was last changed.
metadata(object):metadata.workflowis owned by the workflow module and kept on every write.netDays(integer): Days until the net amount is due.netTotal(number, read-only): Computed from the lines.numberPending(boolean, read-only): A draft invoice or credit note another module made:transactionNumberis its id untilreleaseTransactiongives it the gapless number. Edits keep its number and status.opportunityId(string (uuid)): The crm opportunity the document was made for. Only the format is checked (400invalid,fieldopportunityId). A document made from another one (sourceTransactionId, e.g. the order of an accepted offer) inherits it; an update without it keeps the stored one. Carried in the eventstrade.transaction.*andtrade.offer.accepted.partnerReference(string): The partner's order reference (BT-13).paymentMethodCode(string): Code of the payment method in masterdata.paymentTermCode(string): Code of the payment terms: a snapshot taken when the document is made.paymentTermsText(string): Payment terms as printed text.predecessorId(string (uuid)): Previous version of the same document.recipientAddress(object): Address snapshot of the partner.recipientCompany(string): Company of the recipient.recipientEmail(string): E-mail of the recipient.recipientName(string): Name of the recipient.skontoDays1(integer): Days of the first cash discount.skontoDays2(integer): Days of the second cash discount.skontoRate1(number): Rate in percent of the first cash discount.skontoRate2(number): Rate in percent of the second cash discount.sourceKind(string): Where it came from:MANUAL(default),PORTAL, or the e-invoice/OCR kind of inbound invoices.sourceTransactionId(string (uuid)): Document this one was made from.status(TransactionStatus): Sales statuses areDRAFT,SENT,ACCEPTED,EXPIRED,REVOKED,CONVERTED; delivery notes made from an order areDELIVEREDorCANCELLED; issued invoices and credit notes areISSUED(set only byissueInvoiceDraft); purchase orders, goods receipts, inbound invoices and documents of the snapshot API use their own statuses (e.g.open,posted,MATCHED,issued).taxTotal(number, read-only): Tax total, computed from the lines.tenantName(string, read-only): Name of the tenant.transactionNumber(string): Assigned with the type's prefix when empty on create.transactionType(string): Code of a type of the tenant's catalogue; required on create.typeData(object): Facts of exactly one type (e.g.extractionof inbound invoices,acceptanceof accepted offers,sourcesof a draft invoice,correctedInvoiceandreturnToStockof a credit note,einvoiceof an issued invoice,dropShipDeliveryof a drop-ship delivery note,issueRefusal{reason,problems,at,mspInvoiceId} of a draft invoice whose issue the MSP poster refused – issuing it withissueInvoiceDraftmarks that MSP invoiceposted).updatedAt(string (date-time), read-only): When the transaction was last changed.validUntil(string (date-time)): Offers only.version(integer, read-only): Version of the document (createTransactionRevisionadds one).
Example 201 answer:
{
"addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
"createdAt": "2026-11-19T10:12:00Z",
"currency": "EUR",
"customerNo": "99999",
"documentDate": "2026-11-19T00:00:00Z",
"exchangeRate": 1,
"grossTotal": 272.51,
"headerText": "Gutschrift für einen nicht benötigten Access Point (Rücknahme).",
"id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
"items": [
{
"articleNumber": "NW-2002",
"id": "2f5a6b7c-8d9e-4f0a-9b1c-4d5e6f7a8b01",
"lineData": {
"serialNumbers": [
"AP6-24K0118"
]
},
"name": "WLAN Access Point Wi-Fi 6 – Rücknahme",
"positionNumber": 1,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
"quantity": 1,
"sortOrder": 1,
"sourceLineId": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
"taxRate": 19,
"totalPriceGross": 272.51,
"totalPriceNet": 229,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
"unit": "STK",
"unitPriceNet": 229
}
],
"netDays": 0,
"netTotal": 229,
"opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
"paymentTermsText": "Der Betrag wird Ihnen erstattet.",
"recipientAddress": {
"city": "Schönau am Königssee",
"country": "DE",
"street": "Seestraße 4",
"zip": "83471"
},
"recipientCompany": "Alpenhotel Seeblick GmbH \u0026 Co. KG",
"recipientEmail": "buchhaltung@alpenhotel-seeblick.example",
"recipientName": "Buchhaltung",
"sourceKind": "MANUAL",
"sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"status": "DRAFT",
"taxTotal": 43.51,
"tenantName": "DEMO",
"transactionNumber": "ENTWURF-2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e05",
"transactionType": "CREDIT_NOTE",
"typeData": {
"correctedInvoice": {
"id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"number": "RE-2026-0398"
},
"returnToStock": true
},
"updatedAt": "2026-11-19T10:12:00Z",
"version": 1
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/credit-notes' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"headerText":"Gutschrift für einen nicht benötigten Access Point (Rücknahme).","lines":[{"invoiceLineId":"1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01","quantity":1}],"returnToStock":true}'