## Create a delivery note (tenant:trade:sales:write)

`POST /api/trade/v1/sales/delivery-notes`

Module: Trade · operationId: `createSalesDeliveryNote` · Tag: Transactions · Auth: access token (`Authorization: Bearer <accessToken>`)

`createTransaction` with `transactionType` set to `DELIVERY_NOTE`.

### 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 type `optional`).
  - `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 of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `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.workflow` is 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: `transactionNumber` is its id until `releaseTransaction` gives 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 (400 `invalid`, `field` `opportunityId`). 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 events `trade.transaction.*` and `trade.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 are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); 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. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `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 (`createTransactionRevision` adds one).

Example:

```json
{
  "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

- **201** The transaction (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

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 type `optional`).
  - `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 of `items`.
  - `positionType` (PositionType): Empty is `normal`; the totals count `normal` lines and selected `optional` lines. (one of `normal`, `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.workflow` is 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: `transactionNumber` is its id until `releaseTransaction` gives 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 (400 `invalid`, `field` `opportunityId`). 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 events `trade.transaction.*` and `trade.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 are `DRAFT`, `SENT`, `ACCEPTED`, `EXPIRED`, `REVOKED`, `CONVERTED`; delivery notes made from an order are `DELIVERED` or `CANCELLED`; issued invoices and credit notes are `ISSUED` (set only by `issueInvoiceDraft`); 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. `extraction` of inbound invoices, `acceptance` of accepted offers, `sources` of a draft invoice, `correctedInvoice` and `returnToStock` of a credit note, `einvoice` of an issued invoice, `dropShipDelivery` of a drop-ship delivery note, `issueRefusal` {`reason`, `problems`, `at`, `mspInvoiceId`} of a draft invoice whose issue the MSP poster refused – issuing it with `issueInvoiceDraft` marks that MSP invoice `posted`).
- `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 (`createTransactionRevision` adds one).

Example 201 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c04",
  "createdAt": "2026-11-19T11:30:00Z",
  "currency": "EUR",
  "customerNo": "99999",
  "deliveryDate": "2026-11-20T00:00:00Z",
  "documentDate": "2026-11-19T00:00:00Z",
  "exchangeRate": 1,
  "grossTotal": 259.42,
  "headerText": "Ersatz für zwei defekte Headsets am Empfang",
  "id": "4c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
  "items": [
    {
      "articleNumber": "HW-1007",
      "id": "5e8f9a0b-1c2d-4e3f-8a4b-6c7d8e9f0a01",
      "name": "Headset USB Stereo mit Geräuschunterdrückung",
      "positionNumber": 1,
      "positionType": "normal",
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c07",
      "quantity": 2,
      "sortOrder": 1,
      "taxRate": 19,
      "totalPriceGross": 259.42,
      "totalPriceNet": 218,
      "transactionId": "4c7d8e9f-0a1b-4c2d-9e3f-5a6b7c8d9e01",
      "unit": "STK",
      "unitPriceNet": 109
    }
  ],
  "netTotal": 218,
  "recipientAddress": {
    "city": "Landshut",
    "country": "DE",
    "street": "Bahnhofstraße 8",
    "zip": "84028"
  },
  "recipientCompany": "Gemeinschaftspraxis Dr. Lindner \u0026 Kollegen",
  "recipientName": "Petra Kraus",
  "sourceKind": "MANUAL",
  "status": "DRAFT",
  "taxTotal": 41.42,
  "tenantName": "DEMO",
  "transactionNumber": "LS-2026-0212",
  "transactionType": "DELIVERY_NOTE",
  "updatedAt": "2026-11-19T11:30:00Z",
  "version": 1
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/sales/delivery-notes' \
  -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"}'
```
