Replace a transaction (tenant:trade:sales|purchasing|inbound:write by document type)
PUT /api/trade/v1/sales/transactions/{id}
Module: Trade · operationId: updateTransaction · Tag: Transactions · Auth: access token (Authorization: Bearer <accessToken>)
Replaces the header with the body (send the complete document). items, when present, replace
all lines; totals are recomputed from the lines in the body, so send items with every update.
Kept regardless of the body: metadata.workflow, type_data.acceptance, an existing
frozenSnapshot and the number of inbound invoices. externalTransactionNumber is only written
for purchase orders. A delivery note made from an order changes only in its header; its status, number, order link,
totals and lines stay (409 for a new status or items). A draft invoice made from delivery notes or an order
(placeholder number ENTWURF-<id>) keeps its number, status, order link and typeData.sources; a line linked to an
order line may shrink but not grow (409); a line named twice or a negative quantity is 422. A draft credit note keeps
the same and its typeData.correctedInvoice and returnToStock. An issued invoice or credit note (status ISSUED)
is never changed (409 issued_document), and status ISSUED is set only by issueInvoiceDraft (409 issue_only,
also for a create).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
path | string (uuid) | yes |
Request body
application/json (required)
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:
{
"addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
"currency": "EUR",
"headerText": "Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.",
"items": [
{
"articleNumber": "LNVT14G5",
"discountPercent": 3,
"name": "Lenovo ThinkPad T14 Gen 5",
"positionType": "normal",
"quantity": 5,
"taxRate": 19,
"unit": "Stk",
"unitPriceNet": 1249
},
{
"isOptional": true,
"isSelected": false,
"name": "Docking Station USB-C",
"positionType": "optional",
"quantity": 5,
"taxRate": 19,
"unit": "Stk",
"unitPriceNet": 189
}
],
"recipientAddress": {
"city": "Berlin",
"country": "DE",
"street": "Hauptstraße 12",
"zip": "10115"
},
"recipientCompany": "Muster GmbH",
"recipientEmail": "einkauf@muster-gmbh.de",
"recipientName": "Erika Mustermann",
"transactionType": "OFFER",
"validUntil": "2026-11-30T00:00:00Z"
}
Responses
- 200 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 A delivery note made from an order: status, type and lines are fixed (cancel it with
cancelSalesDeliveryNote). A line of a draft invoice would invoice more than it reserved. An issued invoice or credit note (codeissued_document), or statusISSUEDin the body (codeissue_only). (application/json) - 422 A line of a draft invoice is named twice or has a negative quantity. (
application/json) - 423 An active workflow locks the transaction. (
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-02T09:14:00Z",
"currency": "EUR",
"customerNo": "99999",
"documentDate": "2026-11-02T00:00:00Z",
"exchangeRate": 1,
"footerText": "Wir freuen uns auf Ihren Auftrag.",
"grossTotal": 3940.09,
"headerText": "Vielen Dank für Ihre Anfrage zum WLAN-Ausbau im Gästebereich. Gerne bieten wir Ihnen an:",
"id": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"items": [
{
"articleNumber": "NW-2002",
"discountPercent": 0,
"id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d01",
"name": "WLAN Access Point Wi-Fi 6, Deckenmontage",
"positionNumber": 1,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
"quantity": 6,
"sortOrder": 1,
"taxRate": 19,
"totalPriceGross": 1635.06,
"totalPriceNet": 1374,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"unit": "STK",
"unitPriceNet": 229
},
{
"articleNumber": "NW-2001",
"discountPercent": 0,
"id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d02",
"name": "Switch 24 Port Gigabit PoE+, managed",
"positionNumber": 2,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c01",
"quantity": 1,
"sortOrder": 2,
"taxRate": 19,
"totalPriceGross": 712.81,
"totalPriceNet": 599,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"unit": "STK",
"unitPriceNet": 599
},
{
"articleNumber": "NW-2003",
"discountPercent": 0,
"id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d03",
"name": "Patchkabel Cat.6a 2 m, grau",
"positionNumber": 3,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c03",
"quantity": 20,
"sortOrder": 3,
"taxRate": 19,
"totalPriceGross": 116.62,
"totalPriceNet": 98,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"unit": "STK",
"unitPriceNet": 4.9
},
{
"articleNumber": "DL-9001",
"discountPercent": 0,
"id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d04",
"name": "Technikerstunde vor Ort",
"positionNumber": 4,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c11",
"quantity": 10,
"sortOrder": 4,
"taxRate": 19,
"totalPriceGross": 1368.5,
"totalPriceNet": 1150,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"unit": "STD",
"unitPriceNet": 115
},
{
"articleNumber": "DL-9004",
"discountPercent": 0,
"id": "8b1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d05",
"name": "Anfahrtspauschale Zone 1",
"positionNumber": 5,
"positionType": "normal",
"productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c14",
"quantity": 2,
"sortOrder": 5,
"taxRate": 19,
"totalPriceGross": 107.1,
"totalPriceNet": 90,
"transactionId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e01",
"unit": "PAU",
"unitPriceNet": 45
}
],
"netDays": 30,
"netTotal": 3311,
"opportunityId": "7d3c0d5e-2f4b-4c47-9c1e-2b8f5d1a6e90",
"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": "katrin.stadler@alpenhotel-seeblick.example",
"recipientName": "Katrin Stadler",
"skontoDays1": 14,
"skontoRate1": 2,
"sourceKind": "MANUAL",
"status": "SENT",
"taxTotal": 629.09,
"tenantName": "DEMO",
"transactionNumber": "AN-2026-0187",
"transactionType": "OFFER",
"updatedAt": "2026-11-02T09:31:00Z",
"validUntil": "2026-12-02T00:00:00Z",
"version": 1
}
Example request
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/sales/transactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","currency":"EUR","headerText":"Vielen Dank für Ihre Anfrage. Gerne bieten wir Ihnen an.","items":[{"articleNumber":"LNVT14G5","discountPercent":3,"name":"Lenovo ThinkPad T14 Gen 5","positionType":"normal","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":1249},{"isOptional":true,"isSelected":false,"name":"Docking Station USB-C","positionType":"optional","quantity":5,"taxRate":19,"unit":"Stk","unitPriceNet":189}],"recipientAddress":{"city":"Berlin","country":"DE","street":"Hauptstraße 12","zip":"10115"},"recipientCompany":"Muster GmbH","recipientEmail":"einkauf@muster-gmbh.de","recipientName":"Erika Mustermann","transactionType":"OFFER","validUntil":"2026-11-30T00:00:00Z"}'