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

```json
{
  "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:

```json
{
  "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

```bash
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"}'
```
