## Optimize a purchase cart (tenant:purchase-cart:write)

`POST /api/trade/v1/purchase-carts/{id}/optimize`

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

Gathers the offers of every enabled distributor connector (and the supplier prices of masterdata articles) for
the lines not ordered yet and splits them by the lowest landed cost (goods plus shipping, surcharges and drop-ship
fees per shipment, `procurement` settings). The proposal is stored at the cart for its current `version`; a
connector that failed is named in `warnings`, a line no usable offer covers in `unassigned`. Accept it with
`acceptPurchaseCartProposal` before the offers expire (`procurement.offerTtlMinutes`).

### Parameters

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

### Responses

- **200** The proposal (`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** The cart does not allow it (`code`): `cart_not_open` (ordered or discarded), `recommendation_not_open`,
`line_ordered` (the line is on a purchase order), `nothing_to_order`, `no_proposal` (optimize first),
`proposal_stale` / `cart_changed` (optimize again), `accept_in_progress` (an optimization, accept or order of
the cart is running; retry shortly), `drop_ship_no_address` (a drop-ship order has no delivery address).
 (`application/json`)
- **502** A dependent service (DMS, masterdata, a distributor) failed or is unreachable. (`application/json`)
- **503** Offers are not available in this installation. (`application/json`)

Fields of the 200 answer:

- `accepted` (object): Per group (supplier and ship-to) the purchase order it became.
- `acceptedAt` (string (date-time)): Set when every group is accepted.
- `cartVersion` (integer): Version of the cart the proposal was computed for.
- `id` (string): Id of the proposal.
- `maxDays` (integer): Longest delivery time of the proposal in days.
- `method` (string): Solver that found the proposal (`exact`, `subsets`, `heuristic`).
- `naiveTotalCents` (integer): Every line at its cheapest offer, each from its own shipment.
- `offers` (object): The offers used, per article key.
- `optimizedAt` (string (date-time)): When the proposal was computed.
- `savingsCents` (integer): Savings against buying every line at its cheapest offer separately, in cents.
- `shipments` (array of object): One future purchase order each (offer key and ship-to).
  - `assignments` (array of object): Cart lines the shipment carries.
    - `lineCents` (integer): Line total in cents: round(`priceCents` × `quantity`).
    - `lineId` (string (uuid)): Id of the cart line.
    - `offerKey` (string): Key of the distributor offer.
    - `priceCents` (integer): Unit price in cents.
    - `quantity` (number): Quantity assigned.
  - `days` (integer): Delivery days.
  - `dropShip` (boolean): The shipment goes straight to the customer.
  - `dropShipFeeCents` (integer): Drop-ship fee in cents.
  - `freightQuoted` (boolean): `shippingCents` is the distributor's freight estimate (Ingram) instead of the configured shipping cost.
  - `goodsCents` (integer): Goods value in cents.
  - `offerKey` (string): Key of the distributor offer the shipment uses.
  - `shipToKey` (string): `stock` or the drop-ship address key.
  - `shippingCents` (integer): Shipping cost in cents.
  - `supplierAddressId` (string): Masterdata address of the supplier.
  - `surchargeCents` (integer): Minimum-order surcharge in cents.
  - `totalCents` (integer): Total of the shipment in cents.
- `totalCents` (integer): Total of the proposal in cents.
- `unassigned` (array of object): Lines (or rests) no usable offer covers.
  - `lineId` (string (uuid)): Id of the cart line.
  - `missingQty` (number): Quantity no offer covers.
  - `reason` (string): Why it could not be assigned (e.g. `insufficient_availability`, `minimum_order_not_reached`).
- `warnings` (array of object): Sources that failed while the offers were gathered; their offers are missing.
  - `connector` (string): Connector that did not answer fully.
  - `message` (string): What went wrong.

Example 200 answer:

```json
{
  "cartVersion": 4,
  "id": "c4f1a2b3-wk47-optimum",
  "maxDays": 2,
  "method": "exact",
  "naiveTotalCents": 222650,
  "offers": {
    "HW-1007": [
      {
        "available": 140,
        "days": 1,
        "distributorId": "70044",
        "distributorName": "Nordlicht IT-Distribution GmbH",
        "fetchedAt": "2026-11-19T07:39:58Z",
        "key": "egis:70044",
        "priceCents": 7900,
        "source": "egis",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
        "supplierArticleNumber": "NL-HS-USB-ANC",
        "supplierName": "Nordlicht IT-Distribution GmbH"
      }
    ],
    "NW-2002": [
      {
        "available": null,
        "days": 2,
        "distributorId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "fetchedAt": "2026-11-19T07:39:58Z",
        "key": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "priceCents": 15900,
        "source": "masterdata",
        "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
        "supplierArticleNumber": "KW-AP-WIFI6",
        "supplierName": "Kabelwerk Süd GmbH"
      }
    ]
  },
  "optimizedAt": "2026-11-19T07:40:00Z",
  "savingsCents": 0,
  "shipments": [
    {
      "assignments": [
        {
          "lineCents": 95400,
          "lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
          "offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
          "priceCents": 15900,
          "quantity": 6
        }
      ],
      "days": 2,
      "dropShip": false,
      "dropShipFeeCents": 0,
      "freightQuoted": false,
      "goodsCents": 95400,
      "offerKey": "masterdata:6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "shipToKey": "stock",
      "shippingCents": 0,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d02",
      "surchargeCents": 0,
      "totalCents": 95400
    },
    {
      "assignments": [
        {
          "lineCents": 126400,
          "lineId": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
          "offerKey": "egis:70044",
          "priceCents": 7900,
          "quantity": 16
        }
      ],
      "days": 1,
      "dropShip": false,
      "dropShipFeeCents": 0,
      "freightQuoted": false,
      "goodsCents": 126400,
      "offerKey": "egis:70044",
      "shipToKey": "stock",
      "shippingCents": 850,
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "surchargeCents": 0,
      "totalCents": 127250
    }
  ],
  "totalCents": 222650,
  "unassigned": [],
  "warnings": []
}
```

### Example request

```bash
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/optimize' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
