ConnectCloud Developers

List purchase recommendations (tenant:trade:purchasing:read)

GET /api/trade/v1/purchase-recommendations

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

Purchase recommendations (Bestellvorschläge), oldest first: the uncovered rest of an open sales order line (source order; drop-ship lines carry the customer's shipTo) and refills of articles below their minimum stock (source stock). They are recomputed in the background whenever orders, purchase orders, goods receipts or stock change, and with recomputePurchaseRecommendations.

Parameters

Name In Type Required Description
status query string (one of open, in_cart, ordered, dismissed)
source query string (one of order, stock)
orderId query string (uuid) Only the recommendations of this sales order.

Responses

  • 200 Recommendations (application/json)
  • 400 Error (application/json)
  • 401 No valid session or bearer token (no body).

Fields of the 200 answer:

  • items (array of PurchaseRecommendation)
    • articleId (string): Masterdata product id (empty for an order line without article).
    • cartId (string (uuid)): The cart of an in_cart recommendation.
    • dismissReason (string): Why it was dismissed; set while dismissed.
    • dropShip (boolean): The supplier delivers straight to the customer (shipTo).
    • id (string (uuid)): Id of the recommendation.
    • key (string): Stable key: the first revision of the order line, or the article and warehouse of a stock refill.
    • orderId (string (uuid)): Sales order the recommendation is for; absent for minimum stock.
    • orderLineId (string (uuid)): The current revision of the sales order line.
    • orderNumber (string): Number of that sales order.
    • pendingNeed (number): Set while in_cart when the need changed since: the current need (0 = no need any more).
    • quantity (number): The need; while in_cart the quantity in the cart.
    • reason (string): Why (German), e.g. Auftrag AB-2026-00012 Pos. 3 nicht gedeckt.
    • removedNeed (number): Set on an open recommendation a person took out of a cart: the automatic cart leaves it alone up to this quantity.
    • shipTo (object): Delivery address of a drop-ship recommendation.
    • source (string): order: the uncovered rest of a sales order line; stock: refill below the minimum stock. (one of order, stock)
    • status (string): open, in_cart, ordered or dismissed. (one of open, in_cart, ordered, dismissed)
    • updatedAt (string (date-time)): When the recommendation was last changed.
    • warehouseId (string): Warehouse of a stock line (empty for drop shipment).
  • total (integer)

Example 200 answer:

{
  "items": [
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "dropShip": false,
      "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "key": "stock:4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07:HAUPT",
      "quantity": 16,
      "reason": "Mindestbestand 10 unterschritten (frei 4)",
      "source": "stock",
      "status": "open",
      "updatedAt": "2026-11-19T06:15:00Z",
      "warehouseId": "HAUPT"
    },
    {
      "articleId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "cartId": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
      "dropShip": false,
      "id": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "key": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "orderId": "2f6b1d84-7c3e-4a5b-9e21-6a0c4d8b1e02",
      "orderLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "orderNumber": "AB-2026-0143",
      "quantity": 6,
      "reason": "Auftrag AB-2026-0143 Pos. 1 nicht gedeckt",
      "source": "order",
      "status": "in_cart",
      "updatedAt": "2026-11-06T10:20:00Z"
    }
  ],
  "total": 2
}

Example request

curl -X GET 'https://api.mbcom.cloud/api/trade/v1/purchase-recommendations' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI