## List purchase carts (tenant:trade:purchasing:read)

`GET /api/trade/v1/purchase-carts`

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

The tenant's carts with their lines, newest first.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | (one of `open`, `ordered`, `discarded`) |

### Responses

- **200** Carts (`application/json`)
- **401** No valid session or bearer token (no body).
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `items` (array of PurchaseCart)
  - `createdAt` (string (date-time)): When the cart was created.
  - `createdBy` (string): Who created the cart.
  - `id` (string (uuid)): Id of the cart.
  - `kind` (string): `auto`: the tenant's single automatic cart (`procurement.autoCart`), "Automatische Vorschläge". (one of `manual`, `auto`)
  - `lines` (array of PurchaseCartLine): Lines of the cart.
    - `articleNumber` (string): Article number in masterdata.
    - `description` (string): Description of the article.
    - `ean` (string): EAN (GTIN) of the article.
    - `flag` (string): Set when the sales order changed after the line went into the cart, e.g. `Kein Bedarf mehr`.
    - `id` (string (uuid)): Id of the cart line.
    - `manufacturer` (string): Manufacturer of the article.
    - `mpn` (string): Manufacturer part number.
    - `pinnedOffer` (string): Offer key the optimizer must use.
    - `poId` (string (uuid)): The purchase order the line is on.
    - `poLineId` (string (uuid)): Purchase order line the line became once accepted.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `recommendationId` (string (uuid)): Purchase recommendation the line came from.
    - `shipTo` (object): Customer address of a drop-ship line.
    - `shipToKind` (string): `stock` or `drop_ship`. (one of `stock`, `drop_ship`)
    - `sourceIdentifiers` (object): Article id per connector, e.g. `egis`: PCS number.
    - `sourceLineId` (string (uuid)): The sales order line (current revision).
    - `unit` (string): Unit of measure.
  - `name` (string): Name of the cart.
  - `proposal` (PurchaseCartProposal): The optimizer's split of the cart; amounts are net EUR cents.
    - `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.
  - `status` (string): Status of the cart (`open`, `ordered`, `discarded`). (one of `open`, `ordered`, `discarded`)
  - `updatedAt` (string (date-time)): When the cart was last changed.
  - `version` (integer): Raised by every change; a proposal is valid for one version.
- `total` (integer)

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-11-17T08:00:00Z",
      "createdBy": "anna.weber@muster-it.example",
      "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
      "kind": "manual",
      "name": "Wochenbestellung KW 47",
      "status": "open",
      "updatedAt": "2026-11-19T07:35:00Z",
      "version": 4
    },
    {
      "createdAt": "2026-09-01T06:00:00Z",
      "createdBy": "system",
      "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d02",
      "kind": "auto",
      "name": "Automatische Vorschläge",
      "status": "open",
      "updatedAt": "2026-11-19T06:15:00Z",
      "version": 11
    }
  ],
  "total": 2
}
```

### Example request

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