## 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:

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

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