Add a recurring position to a contract (tenant:trade:msp:write)
POST /api/trade/v1/contracts/{id}/items
Module: Trade · operationId: createContractItem · Tag: Contracts · Auth: access token (Authorization: Bearer <accessToken>)
fixed positions are billed by their cadence (empty: the contract's) from their start (else the contract's);
monthly ones are prorated by days in their first and last month. A usage position sets the price of its
article for the contract's usage. MSP drafts become stale.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id |
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) orusage(the collected MSP usage). (one offixed,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:
{
"articleNumber": "MS-FLAT",
"name": "Managed Service Pauschale",
"quantity": 1,
"source": "fixed",
"unitPrice": 310
}
Responses
- 201 Created (
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_enabledanditc_no_supplier(upload only), orconflict(e.g. a stale draft, open problems, an invoice past draft). (application/json)
Fields of the 201 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) orusage(the collected MSP usage). (one offixed,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 201 answer:
{
"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
curl -X POST 'https://api.mbcom.cloud/api/trade/v1/contracts/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/items' \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H 'Content-Type: application/json' \
--data '{"articleNumber":"MS-FLAT","name":"Managed Service Pauschale","quantity":1,"source":"fixed","unitPrice":310}'