Issue a draft invoice or credit note (tenant:trade:invoice:issue)
POST /api/trade/v1/invoices/{id}/issue
Module: Trade · operationId: issueInvoiceDraft · Tag: Issued documents · Auth: access token (Authorization: Bearer <accessToken>)
Turns a DRAFT invoice or credit note into an issued one (status ISSUED) in one database transaction: the next
gapless number of the type (RE-<year>-<nnnnn>, credit notes GS-…; prefix of the type catalogue), invoice date
today, due date from the net days, an XRechnung 3.0 (CII) written from the seller profile and the customer's
masterdata address and validated with the KoSIT rules – an invalid one is refused with its findings and
nothing is numbered –, the XML archived in DMS (typeData.einvoice; no PDF any more – documents issued earlier
keep their pdfDocumentId), the check listed among the e-invoice checks, and with send the mail with the XML
through comms (to recipient, else the customer's invoice e-mail). Publishes trade.invoice.issued. An issued
document is never changed again.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json
recipient(string (email)): Overrides the customer's invoice e-mail (max length 254)send(boolean): Mail the invoice to the customerversion(integer): The draft version you read; a newer one answers 409
Example:
{
"recipient": "buchhaltung@alpenhotel-seeblick.example",
"send": true,
"version": 1
}
Responses
- 200 The transaction (
application/json) - 400 Error (
application/json) - 401 No valid session or bearer token (no body).
- 403 Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (
application/json) - 404 Not found in the tenant. (
application/json) - 409 The document is no draft any more, or the draft changed since
version. (application/json) - 422 Facts are missing (
code: not_ready,details.problems), or the XRechnung fails the KoSIT rules (code: einvoice_invalid,details.findings). (application/json) - 423 An active workflow locks the transaction. (
application/json) - 502 A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (
application/json)
Fields of the 200 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 200 answer:
{
"addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c01",
"createdAt": "2026-11-18T08:20:00Z",
"currency": "EUR",
"customerNo": "99999",
"deliveryDate": "2026-11-17T00:00:00Z",
"documentDate": "2026-11-19T00:00:00Z",
"dueDate": "2026-12-19T00:00:00Z",
"exchangeRate": 1,
"grossTotal": 2464.49,
"headerText": "Wir berechnen Ihnen die Lieferung vom 17.11.2026:",
"id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"items": [
{
"articleNumber": "NW-2002",
"id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a01",
"lineData": {
"serialNumbers": [
"AP6-24K0113",
"AP6-24K0114",
"AP6-24K0115",
"AP6-24K0116",
"AP6-24K0117",
"AP6-24K0118"
]
},
"name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
"positionNumber": 1,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
"quantity": 6,
"sortOrder": 1,
"sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f01",
"taxRate": 19,
"totalPriceGross": 1635.06,
"totalPriceNet": 1374,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"unit": "STK",
"unitPriceNet": 229
},
{
"articleNumber": "NW-2001",
"id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a02",
"lineData": {
"serialNumbers": [
"SW24-9K2207"
]
},
"name": "Switch 24 Port Gigabit PoE+, managed",
"positionNumber": 2,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
"quantity": 1,
"sortOrder": 2,
"sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f02",
"taxRate": 19,
"totalPriceGross": 712.81,
"totalPriceNet": 599,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"unit": "STK",
"unitPriceNet": 599
},
{
"articleNumber": "NW-2003",
"id": "1e4f5a6b-7c8d-4e9f-8a0b-3c4d5e6f7a03",
"name": "Patchkabel Cat.6a 2 m, grau",
"positionNumber": 3,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
"quantity": 20,
"sortOrder": 3,
"sourceLineId": "0d3e4f5a-6b7c-4d8e-9f0a-2b3c4d5e6f03",
"taxRate": 19,
"totalPriceGross": 116.62,
"totalPriceNet": 98,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e04",
"unit": "STK",
"unitPriceNet": 4.9
}
],
"netDays": 30,
"netTotal": 2071,
"opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
"partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
"paymentTermCode": "14T2",
"paymentTermsText": "14 Tage 2 % Skonto, 30 Tage netto",
"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",
"skontoDays1": 14,
"skontoRate1": 2,
"sourceKind": "MANUAL",
"sourceTransactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
"status": "ISSUED",
"taxTotal": 393.49,
"tenantName": "DEMO",
"transactionNumber": "RE-2026-0398",
"transactionType": "INVOICE",
"typeData": {
"einvoice": {
"fileName": "RE-2026-0398.xml",
"xmlDocumentId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c01"
},
"sources": [
{
"id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e03",
"number": "LS-2026-0211",
"orderNumber": "AB-2026-0143",
"partnerReference": "Auftrag vom 06.11.2026, K. Stadler",
"type": "DELIVERY_NOTE"
}
]
},
"updatedAt": "2026-11-19T09:05:00Z",
"version": 1
}
Example request
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/invoices/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/issue' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"recipient":"buchhaltung@alpenhotel-seeblick.example","send":true,"version":1}'