ConnectCloud Developers

Create an offer (tenant:trade:sales:write)

POST /api/trade/v1/sales/offers

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

createTransaction with transactionType set to OFFER. validUntil is stored with the offer. opportunityId links the offer to a crm opportunity (400 invalid with field opportunityId when it is no UUID).

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:

{
  "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:

{
  "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 POST 'https://api.mbcom.cloud/api/trade/v1/sales/offers' \
  -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"}'

View as Markdown · Interactive reference · OpenAPI