ConnectCloud Developers

Send a purchase order to its supplier (tenant:purchase-order:send)

POST /api/trade/v1/purchase-orders/{id}/send

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

Sends the order once through the chosen channel (channel, else the resolved one; see getPurchaseOrderOrdering): mail mails it from the tenant's mailbox (the trade mail channel, else the tenant's default e-mail channel) to recipient or the supplier's order mail address – the state and the mail commit together (idempotency key trade.purchase_order_supplier:<id>:<revision>); ingram orders through the Ingram Micro reseller API (ordering switched on in the ITSP settings) with the order number as Ingram's customerOrderNumber, the Ingram part numbers of the preview, the tenant's address as ship-to and line numbers 1…n (supplierOrder.lineMap). The state is sending (with attemptedAt and the sentLines) before Ingram gets the order; an answer without verdict keeps it and is answered 502. A send of an order left sending or failed first looks it up at Ingram by its number, before any preview, and takes an order whose lines are the sent ones (never ordering twice) – one with other lines makes it failed and is answered 409; without a hit it is sent anew. While the last attempt is younger than two minutes it may still be running and a send is answered 409; while it is younger than 30 minutes a search without hit is answered 409 as well (Ingram's search may lag behind; nothing is created again). A clear refusal by Ingram is failed and 502. A partly taken order (Ingram 207) is sent with supplierOrder.rejectedLines; a split order keeps the further Ingram order numbers in related. manual records an order placed by other means with the supplier's order number (externalOrderNumber, which also fills an empty external number); it may also record a failed API order the person checked at the distributor. The state is stored at the order (supplierOrder); a sent order turns a draft open and publishes trade.purchaseorder.sent. An order sent already (also through EGIS), whose earlier API send is still open or failed (only that channel may continue, a failed one also manual), or neither draft nor open is answered 409, a supplier ordered through EGIS 409 with the EGIS route, an order that lacks data 422 with the preview, an order locked by a running workflow 423 before anything goes out.

Parameters

Name In Type Required Description
id path string (uuid) yes

Request body

application/json

  • channel (string): Another available channel than the resolved one; mail also with only a recipient. (one of ingram, infinigate, mail, manual)
  • comment (string): Remark for the supplier. (max length 500)
  • externalOrderNumber (string): Manual only: the supplier's order number. (max length 64)
  • recipient (string (email)): Mail only: overrides the supplier's order mail address. (max length 254)
  • requestedDeliveryDate (string (date)): Requested delivery date.

Example:

{
  "channel": "mail",
  "comment": "Lieferung bitte an Lager 2",
  "requestedDeliveryDate": "2026-11-03"
}

Responses

  • 200 Sent (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 Sent already (also through EGIS), an earlier API send still in flight or not found yet, an order at the distributor that differs, another channel while an API send is open or failed, or neither draft nor open – a plain error (German text); a supplier ordered through EGIS is answered with code use_egis, details.channel egis and the EGIS route (details.route). (application/json)
  • 422 The channel is not available for the supplier (channel_not_available), or the order lacks data the channel needs (not_ready, details.preview names it, e.g. the mail recipient). (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:

  • createdAt (string (date-time)): When the purchase order was created.
  • currency (string): Currency (ISO 4217).
  • dropShip (object): Drop shipment: the customer's delivery address (name, company, street, zip, city, country); the supplier delivers there and no stock is booked.
  • egis (EgisOrder): The order as EGIS knows it (sent through EGIS), with the distributor's follow-up documents.
    • cargoInsurance (number): Cargo insurance charged.
    • confirmations (array of object): Order confirmations of the distributor.
      • date (string (date)): Date of the confirmation.
      • distributorOrderNumber (string): The distributor's order number.
      • id (integer): EGIS id of the confirmation.
      • lines (array of object): Confirmed lines.
        • deliveryDate (string (date)): Expected delivery date.
        • position (integer): Purchase order line.
        • quantity (number): Planned delivery quantity.
        • supplierArticleNumber (string): The distributor's article number.
        • unitPrice (number): Confirmed net unit price.
    • deliveryNotes (array of object): Delivery notes of the distributor.
      • date (string (date)): Date of the delivery note.
      • deliveryNoteId (string (uuid)): The inbound delivery note made from it.
      • id (string): EGIS delivery note id.
      • lines (array of object): Delivered lines.
        • description (string): Description of the article.
        • ean (string): EAN (GTIN) of the article.
        • mpn (string): Manufacturer part number.
        • position (integer): Position number of the line.
        • quantity (number): Quantity delivered.
        • serialNumbers (array of string): Serial numbers.
        • supplierArticleNumber (string): The distributor's article number.
        • unit (string): Unit of measure.
      • number (string): The distributor's delivery note number.
      • packages (array of object): Packages of the shipment.
        • number (string): Tracking number of the package.
        • trackingUrl (string (uri)): Tracking link of the package.
      • shipper (string): Carrier of the shipment.
    • distributorId (string): EGIS distributor number.
    • distributorName (string): Name of the distributor the order went to.
    • distributorOrderNumber (string): The distributor's own order number (also stored as the external number of the order when empty).
    • freightCharge (number): Freight including additional charges.
    • invoices (array of object): Structured invoice data of the distributor (no invoice document); a second source of the purchase order check of inbound invoices.
      • currency (string): Currency (ISO 4217).
      • date (string (date)): Invoice date.
      • grossAmount (number): Gross amount of the invoice.
      • id (integer): EGIS id of the invoice.
      • lines (array of object): Invoiced lines.
        • description (string): Description of the article.
        • netTotal (number): Net total of the line.
        • position (integer): Purchase order line; missing for lines that were not ordered (freight, insurance).
        • quantity (number): Quantity invoiced.
        • supplierArticleNumber (string): The distributor's article number.
        • taxRate (number): Percent.
        • unitPrice (number): Net unit price.
      • netAmount (number): Net amount of the invoice.
      • number (string): The distributor's invoice number.
      • vatAmount (number): VAT amount of the invoice.
    • link (string (uri)): The order in the EGIS web application.
    • orderDate (string (date)): Order date at EGIS.
    • orderNumber (string): EGIS order number (leading zeros kept); invoices naming it find the order.
    • paymentMethod (string): Payment method of the order at EGIS.
    • sentAt (string (date-time)): When the order was sent to EGIS.
    • smallQuantitiesMarkup (number): Small-quantity markup charged.
    • statusCode (integer): -1 error, 0 stored in EGIS, 10 sent to the distributor, 20 rejected, 30 confirmed, 40 delivered, 50 invoiced. Orders in -1, 20 and 50 are no longer followed. (one of -1, 0, 10, 20, 30, 40, 50)
    • statusText (string): Status text of EGIS.
  • goodsReceipts (array of object): Goods receipts of the purchase order.
    • grNumber (string): Number of the goods receipt.
    • id (string (uuid)): Id of the goods receipt.
    • receivedAt (string (date-time)): When the goods were received.
    • status (string): Status of the goods receipt.
  • id (string (uuid)): Id of the purchase order.
  • lines (array of POLine): Empty in lists.
    • articleNumber (string): Article number in masterdata.
    • description (string): Description of the line.
    • ean (string): EAN (GTIN) of the article.
    • id (string (uuid)): Id of the purchase order line.
    • invoicedQty (number): Always 0.
    • mpn (string): Manufacturer part number.
    • orderedQty (number): Quantity ordered.
    • pcsNumber (string): EGIS PCS number of the article (purchase cart orders).
    • position (integer): Position number of the line.
    • productId (string (uuid)): Masterdata article (product) id.
    • receivedQty (number): Quantity received.
    • sourceLineId (string (uuid)): The sales order line the line was bought for (set by the purchase cart; never by a client).
    • supplierArticleNumber (string): The distributor's article number of the offer the purchase cart chose.
    • taxRate (number): Tax rate in percent.
    • unit (string): Unit of measure.
    • unitPrice (number): Net unit price.
  • netTotal (number): Net total of the purchase order.
  • orderDate (string (date)): Order date.
  • poNumber (string): Number of the purchase order.
  • sourceOrders (array of object): The sales orders the lines were bought for.
    • id (string (uuid)): Id of the sales order.
    • number (string): Number of the sales order.
  • sourcing (object): How a purchase cart chose the order (generated orders only). The sending channel prefers its source.
    • cartId (string (uuid)): Purchase cart the order was made from.
    • distributorId (string): Distributor the cart optimizer chose.
    • goodsCents (integer): Goods value of the shipment in cents.
    • offerKey (string): Key of the distributor offer.
    • offerKeys (array of string): Every offer key of the order when several share the supplier.
    • optimizedAt (string (date-time)): When the proposal was computed.
    • priceCents (integer): Landed cost (goods and shipment costs) in euro cents.
    • proposalId (string (uuid)): Proposal of the cart the order was made from.
    • shippingCents (integer): Shipping cost of the shipment in cents.
    • source (string): Offer source: egis, ingram, infinigate or masterdata.
  • status (PurchaseOrderStatus): (one of draft, open, partially_received, received, closed, cancelled)
  • supplierAddressId (string (uuid)): Masterdata address of the supplier.
  • supplierOrder (SupplierOrder): The order as its supplier knows it, when it was sent through another channel than EGIS.
    • attemptedAt (string (date-time)): When the last API send started.
    • awaitingDocuments (boolean): A shipped order is still followed: a shipment's delivery note, an announced invoice or a re-check of the inbound invoices is missing.
    • channel (string): How the order went out; manual: ordered by other means and recorded. (one of ingram, infinigate, mail, manual)
    • comment (string): Remark of the last send; a mail sent again without one repeats it.
    • error (string): Why the last send or refresh failed.
    • expectedDeliveryDate (string (date)): Latest delivery date the supplier expects for its open lines (Ingram: estimated, else promised delivery date, else backorder ETA).
    • followError (string): What the follow-up could not resolve and a person has to (German), e.g. shipped lines without shipment data or a shipment that could not be taken over.
    • invoices (array of object): Invoices the supplier reported.
      • date (string (date)): Invoice date.
      • grossTotal (number): Gross total.
      • netTotal (number): Net total.
      • number (string): Invoice number of the supplier.
    • lastFollowedAt (string (date-time)): When the supplier's answer last changed the order (automatic follow-up or refresh).
    • lineMap (object): Supplier line number → purchase order line id.
    • orderNumber (string): The supplier's order number (also stored as the external number of the order when empty).
    • recipient (string (email)): Where the mail went (mail).
    • rejectedLines (array of object): Lines the supplier did not take while taking the rest of the order (Ingram 207).
      • lineId (string (uuid)): Id of the purchase order line.
      • reason (string): The supplier's reason.
      • supplierLineNumber (string): The line number the supplier got (key of lineMap).
    • related (array of string): Further order numbers when the supplier split the order.
    • rematchPending (boolean): The re-check of the inbound invoices after new invoice data failed; the next run retries it.
    • requestedDeliveryDate (string (date)): Requested delivery date of the last send; a mail sent again without one repeats it.
    • revision (integer): Counts the sends of changed content (mail sent again); part of the mail's idempotency key.
    • sentAt (string (date-time)): When the order was sent.
    • sentLines (object): What an API send asked for, by supplier line number (key of lineMap); a lost answer is compared with it.
    • shipments (array of object): Shipments the supplier reported.
      • carrier (string): Carrier of the shipment.
      • deliveryNoteId (string (uuid)): The inbound delivery note made from it.
      • handledManually (boolean): A shipment given up on that a person recorded by hand (acknowledgeSupplierFollowError).
      • id (string): Unique within the order: the supplier's delivery number, else sub order and ship date (Ingram; a shipment without delivery number is taken once its ship date is named; reports of one sub order and day without delivery number are one shipment, a delivery number named later attaches to it, and every later report with that number resolves to the same shipment).
      • invoiceNumber (string): The supplier's invoice of the shipment.
      • lines (array of object): Lines of the shipment.
        • lineId (string (uuid)): Id of the purchase order line.
        • quantity (number): Quantity shipped.
        • serialNumbers (array of string): Serial numbers.
      • number (string): The supplier's delivery note number.
      • shippedAt (string (date-time)): When it was shipped.
      • subOrder (string): The supplier's sub order of the shipment (Ingram).
      • takeoverAttempts (integer): Failed hand-overs as delivery note; after 5 the follow-up stops trying (see followError).
      • takeoverError (string): Why the last hand-over failed.
      • trackingNumber (string): Tracking number of the carrier.
      • trackingUrl (string): Tracking link of the carrier.
    • shipmentsMissingSince (string (date-time)): Since when the supplier calls lines shipped that its shipments do not cover; after 14 days the order counts as shipped with a followError.
    • state (string): State at the supplier (sending, sent, confirmed, partially_shipped, shipped, cancelled, failed). (one of sending, sent, confirmed, partially_shipped, shipped, cancelled, failed)
    • statusText (string): The supplier's status text.
  • updatedAt (string (date-time)): When the purchase order was last changed.

Example 200 answer:

{
  "createdAt": "2026-11-13T09:12:00Z",
  "currency": "EUR",
  "goodsReceipts": [],
  "id": "1b4c5d6e-7f8a-4b9c-8d0e-2f3a4b5c6d68",
  "lines": [
    {
      "articleNumber": "NW-2004",
      "description": "Netzwerkschrank 19 Zoll 12 HE",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e01",
      "invoicedQty": 0,
      "orderedQty": 1,
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c04",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-RACK12HE",
      "taxRate": 19,
      "unit": "STK",
      "unitPrice": 289
    },
    {
      "articleNumber": "NW-2005",
      "description": "Verlegekabel Cat.7 Simplex, 100 m",
      "id": "2c5d6e7f-8a9b-4c0d-9e1f-3a4b5c6d7e02",
      "invoicedQty": 0,
      "orderedQty": 3,
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c05",
      "receivedQty": 0,
      "supplierArticleNumber": "KW-CAT7-100",
      "taxRate": 19,
      "unit": "PAK",
      "unitPrice": 64
    }
  ],
  "netTotal": 481,
  "orderDate": "2026-11-13",
  "poNumber": "BE-2026-00068",
  "status": "open",
  "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
  "supplierOrder": {
    "channel": "mail",
    "comment": "Bitte an den Wareneingang, Tor 2, liefern.",
    "recipient": "bestellung@kabelwerk-sued.example",
    "requestedDeliveryDate": "2026-11-20",
    "revision": 1,
    "sentAt": "2026-11-13T09:20:00Z",
    "state": "sent"
  },
  "updatedAt": "2026-11-13T09:20:00Z"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-orders/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/send' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"channel":"mail","comment":"Lieferung bitte an Lager 2","requestedDeliveryDate":"2026-11-03"}'

View as Markdown · Interactive reference · OpenAPI