ConnectCloud Developers

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) 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:

{
  "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_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 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) 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 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}'

View as Markdown · Interactive reference · OpenAPI