ConnectCloud Developers

Create a contract (tenant:trade:contract:write)

POST /api/trade/v1/contracts

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

Defaults when empty — contractNumber CTR-<n>, contractType CUSTOMER, status DRAFT, billingCadence MONTHLY, currency EUR. contingentPots are created with the contract. Publishes trade.contract.created.

Request body

application/json (required)

  • autoRenew (boolean): The contract renews automatically.
  • backToBackLinks (array of BackToBackLink, read-only): Back-to-back links of the contract.
    • allocatedMargin (number): Margin allocated to the link.
    • createdAt (string (date-time), read-only): When the link was created.
    • customerContractId (string (uuid)): Id of the customer contract.
    • customerNo (string, read-only): Customer number of the tenant.
    • id (string (uuid), read-only): Id of the back-to-back link.
    • notes (string): Free-text notes.
    • supplierContractId (string (uuid)): Id of the supplier contract.
    • tenantName (string, read-only): Name of the tenant.
  • billingCadence (string): How often the contract is billed. (one of MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_OFF)
  • contingentPots (array of object): Hour contingents; only written on create.
    • contractId (string (uuid), read-only): Id of the contract.
    • createdAt (string (date-time), read-only): When the hour contingent was created.
    • id (string (uuid), read-only): Id of the hour contingent.
    • name (string): Name of the hour contingent.
    • remainingHours (number, read-only): Hours left.
    • rolloverAllowed (boolean): Unused hours roll over into the next period.
    • totalHours (number): Hours of the contingent.
    • updatedAt (string (date-time), read-only): When the hour contingent was last changed.
    • usedHours (number): Hours used.
    • validUntil (string (date-time)): Last day the hours can be used.
  • contractNumber (string): CTR-<n> when empty on create; never changed by an update.
  • contractType (ContractType): (one of CUSTOMER, SUPPLIER)
  • createdAt (string (date-time), read-only): When the contract was created.
  • cspSubscriptionId (string): Microsoft CSP subscription of the contract.
  • cspTenantId (string): Microsoft CSP tenant.
  • currency (string): Currency (ISO 4217).
  • customerNo (string, read-only): Customer number of the tenant.
  • description (string): Description of the contract.
  • endDate (string (date-time)): End of the contract; absent when open-ended.
  • id (string (uuid), read-only): Id of the contract.
  • leasingRate (number): Leasing rate per billing period.
  • marginPercentage (number): Margin in percent.
  • metadata (object): Free-form metadata.
  • netAmount (number): Net amount per billing period.
  • noticePeriodDays (integer): Notice period in days.
  • partnerId (string (uuid)): Masterdata address of the partner.
  • partnerName (string): Name of the customer or supplier.
  • startDate (string (date-time)): Start of the contract.
  • status (ContractStatus): (one of DRAFT, ACTIVE, EXPIRED, TERMINATED, CANCELLED)
  • tenantName (string, read-only): Name of the tenant.
  • title (string): Title of the contract.
  • updatedAt (string (date-time), read-only): When the contract was last changed.

Example:

{
  "autoRenew": true,
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "name": "Supportstunden 2026",
      "rolloverAllowed": false,
      "totalHours": 40,
      "usedHours": 0
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "currency": "EUR",
  "netAmount": 490,
  "noticePeriodDays": 90,
  "partnerName": "Muster GmbH",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "title": "IT-Wartungsvertrag Standard"
}

Responses

  • 201 Created (application/json)
  • 400 Error (application/json)
  • 401 No valid session or bearer token (no body).

Fields of the 201 answer:

  • autoRenew (boolean): The contract renews automatically.
  • backToBackLinks (array of BackToBackLink, read-only): Back-to-back links of the contract.
    • allocatedMargin (number): Margin allocated to the link.
    • createdAt (string (date-time), read-only): When the link was created.
    • customerContractId (string (uuid)): Id of the customer contract.
    • customerNo (string, read-only): Customer number of the tenant.
    • id (string (uuid), read-only): Id of the back-to-back link.
    • notes (string): Free-text notes.
    • supplierContractId (string (uuid)): Id of the supplier contract.
    • tenantName (string, read-only): Name of the tenant.
  • billingCadence (string): How often the contract is billed. (one of MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY, ONE_OFF)
  • contingentPots (array of object): Hour contingents; only written on create.
    • contractId (string (uuid), read-only): Id of the contract.
    • createdAt (string (date-time), read-only): When the hour contingent was created.
    • id (string (uuid), read-only): Id of the hour contingent.
    • name (string): Name of the hour contingent.
    • remainingHours (number, read-only): Hours left.
    • rolloverAllowed (boolean): Unused hours roll over into the next period.
    • totalHours (number): Hours of the contingent.
    • updatedAt (string (date-time), read-only): When the hour contingent was last changed.
    • usedHours (number): Hours used.
    • validUntil (string (date-time)): Last day the hours can be used.
  • contractNumber (string): CTR-<n> when empty on create; never changed by an update.
  • contractType (ContractType): (one of CUSTOMER, SUPPLIER)
  • createdAt (string (date-time), read-only): When the contract was created.
  • cspSubscriptionId (string): Microsoft CSP subscription of the contract.
  • cspTenantId (string): Microsoft CSP tenant.
  • currency (string): Currency (ISO 4217).
  • customerNo (string, read-only): Customer number of the tenant.
  • description (string): Description of the contract.
  • endDate (string (date-time)): End of the contract; absent when open-ended.
  • id (string (uuid), read-only): Id of the contract.
  • leasingRate (number): Leasing rate per billing period.
  • marginPercentage (number): Margin in percent.
  • metadata (object): Free-form metadata.
  • netAmount (number): Net amount per billing period.
  • noticePeriodDays (integer): Notice period in days.
  • partnerId (string (uuid)): Masterdata address of the partner.
  • partnerName (string): Name of the customer or supplier.
  • startDate (string (date-time)): Start of the contract.
  • status (ContractStatus): (one of DRAFT, ACTIVE, EXPIRED, TERMINATED, CANCELLED)
  • tenantName (string, read-only): Name of the tenant.
  • title (string): Title of the contract.
  • updatedAt (string (date-time), read-only): When the contract was last changed.

Example 201 answer:

{
  "autoRenew": true,
  "backToBackLinks": [
    {
      "allocatedMargin": 42,
      "createdAt": "2026-01-05T09:00:00Z",
      "customerContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "customerNo": "99999",
      "id": "6b7c8d9e-0f1a-4b2c-9d3e-4f5a6b7c8d01",
      "notes": "Cloud-Server kanzlei-srv01 bei ITC Riemer",
      "supplierContractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "tenantName": "DEMO"
    }
  ],
  "billingCadence": "MONTHLY",
  "contingentPots": [
    {
      "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "createdAt": "2025-12-12T10:00:00Z",
      "id": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c01",
      "name": "Supportstunden 2026",
      "remainingHours": 14.5,
      "rolloverAllowed": false,
      "totalHours": 24,
      "updatedAt": "2026-11-14T16:30:00Z",
      "usedHours": 9.5,
      "validUntil": "2026-12-31T00:00:00Z"
    }
  ],
  "contractNumber": "V-2026-0007",
  "contractType": "CUSTOMER",
  "createdAt": "2025-12-12T10:00:00Z",
  "cspTenantId": "8d2f4a6b-1c3e-4f5a-9b7c-0d1e2f3a4b5c",
  "currency": "EUR",
  "customerNo": "99999",
  "description": "Betreuung der 12 Arbeitsplätze, Fernwartung, Microsoft-365-Lizenzen nach Verbrauch und Cloud-Server bei ITC.",
  "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
  "marginPercentage": 18,
  "metadata": {},
  "netAmount": 180,
  "noticePeriodDays": 90,
  "partnerId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
  "partnerName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
  "startDate": "2026-01-01T00:00:00Z",
  "status": "ACTIVE",
  "tenantName": "DEMO",
  "title": "Managed Service Arbeitsplätze und Microsoft 365",
  "updatedAt": "2026-10-02T08:15:00Z"
}

Example request

curl -X POST 'https://api.mbcom.cloud/api/trade/v1/contracts' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"autoRenew":true,"billingCadence":"MONTHLY","contingentPots":[{"name":"Supportstunden 2026","rolloverAllowed":false,"totalHours":40,"usedHours":0}],"contractNumber":"V-2026-0007","contractType":"CUSTOMER","currency":"EUR","netAmount":490,"noticePeriodDays":90,"partnerName":"Muster GmbH","startDate":"2026-01-01T00:00:00Z","status":"ACTIVE","title":"IT-Wartungsvertrag Standard"}'

View as Markdown · Interactive reference · OpenAPI