## Replace a recurring position of a contract (tenant:trade:msp:write)

`PUT /api/trade/v1/contracts/{id}/items/{itemId}`

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

### Parameters

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

### Request body

`application/json` (required)

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.

Example:

```json
{
  "articleNumber": "DL-9005",
  "billingCadence": "",
  "name": "Supportpauschale Fernwartung, monatlich",
  "quantity": 1,
  "sortOrder": 1,
  "source": "fixed",
  "startDate": "2026-01-01",
  "unitPrice": 180
}
```

### Responses

- **200** Updated (`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 state does not allow it: `month_closed` (an invoice of the month is approved or booked), `msp_disabled`, `collection_incomplete` (not every active connector has collected the month), `run_in_progress`, `itc_not_enabled` and `itc_no_supplier` (upload only), or `conflict` (e.g. a stale draft, open problems, an invoice past draft). (`application/json`)

Fields of the 200 answer:

- `articleNumber` (string, required): Article number in masterdata. (max length 100)
- `quantity` (number, required): Quantity per billing period (greater than 0).
- `billingCadence` (string): Empty: the contract's cadence, also after it changes. (one of ``, `MONTHLY`, `QUARTERLY`, `SEMI_ANNUALLY`, `ANNUALLY`, `ONE_OFF`)
- `endDate` (string (date)): Last day the position is billed (YYYY-MM-DD).
- `name` (string): Name printed on the invoice; empty uses the article name. (max length 300)
- `sortOrder` (integer): Sort order (ascending).
- `source` (string): `fixed` (the quantity) or `usage` (the collected MSP usage). (one of `fixed`, `usage`; default `"fixed"`)
- `startDate` (string (date)): First day the position is billed (YYYY-MM-DD).
- `unitPrice` (number): Net price; empty: the masterdata article's price.
- `contractId` (string (uuid)): Id of the contract.
- `id` (string (uuid)): Id of the contract item.

Example 200 answer:

```json
{
  "articleNumber": "DL-9005",
  "billingCadence": "",
  "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "id": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
  "name": "Supportpauschale Fernwartung, monatlich",
  "quantity": 1,
  "sortOrder": 1,
  "source": "fixed",
  "startDate": "2026-01-01",
  "unitPrice": 180
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"articleNumber":"DL-9005","billingCadence":"","name":"Supportpauschale Fernwartung, monatlich","quantity":1,"sortOrder":1,"source":"fixed","startDate":"2026-01-01","unitPrice":180}'
```
