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

`PATCH /api/trade/v1/purchase-carts/{id}`

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

Only open carts. The proposal stays valid.

### Parameters

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

### Request body

`application/json` (required)

- `name` (string, required)

Example:

```json
{
  "name": "Wochenbestellung KW 47"
}
```

### Responses

- **200** Renamed (`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** 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`)
- **422** The input is not valid for the stored data. (`application/json`)

Fields of the 200 answer:

- `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.

Example 200 answer:

```json
{
  "createdAt": "2026-11-17T08:00:00Z",
  "createdBy": "anna.weber@muster-it.example",
  "id": "7b0c1d2e-3f4a-4b5c-8d6e-8f9a0b1c2d01",
  "kind": "manual",
  "lines": [
    {
      "articleNumber": "NW-2002",
      "description": "WLAN Access Point Wi-Fi 6, Deckenmontage",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e01",
      "manufacturer": "Kabelwerk",
      "mpn": "AP-WIFI6-C",
      "position": 1,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7c02",
      "quantity": 6,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c02",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "masterdata": "KW-AP-WIFI6"
      },
      "sourceLineId": "9c2d3e4f-5a6b-4c7d-8e8f-1a2b3c4d5e01",
      "unit": "STK"
    },
    {
      "articleNumber": "HW-1007",
      "description": "Headset USB Stereo mit Geräuschunterdrückung",
      "ean": "4061234500076",
      "id": "8c1d2e3f-4a5b-4c6d-9e7f-9a0b1c2d3e02",
      "manufacturer": "Nordlicht",
      "mpn": "HS-USB-ANC",
      "pinnedOffer": "egis:70044",
      "position": 2,
      "productId": "4b7d9f13-5e6a-4c8b-a1d2-3e4f5a6b7d07",
      "quantity": 16,
      "recommendationId": "6a9b0c1d-2e3f-4a4b-9c5d-7e8f9a0b1c01",
      "shipToKind": "stock",
      "sourceIdentifiers": {
        "egis": "PCS400942",
        "masterdata": "NL-HS-USB-ANC"
      },
      "unit": "STK"
    }
  ],
  "name": "Wochenbestellung KW 47",
  "status": "open",
  "updatedAt": "2026-11-19T07:35:00Z",
  "version": 4
}
```

### Example request

```bash
curl -X PATCH 'https://api.mbcom.cloud/api/trade/v1/purchase-carts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"name":"Wochenbestellung KW 47"}'
```
