## List contracts (tenant:trade:contract:read)

`GET /api/trade/v1/contracts`

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

Newest first (creation time, then id), without contingents and links; pages by keyset (`nextCursor`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `search` | query | string |  | Substring of the number, the partner's number or the partner name (case-insensitive). |
| `type` | query | ContractType |  | (one of `CUSTOMER`, `SUPPLIER`) |
| `status` | query | ContractStatus |  | (one of `DRAFT`, `ACTIVE`, `EXPIRED`, `TERMINATED`, `CANCELLED`) |
| `limit` | query | integer |  | 1–100 (else `400 invalid`). (default `50`; max 100) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

- **200** A page of contracts (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).

Fields of the 200 answer:

- `items` (array of Contract, 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.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "V-2026-0007",
      "contractType": "CUSTOMER",
      "createdAt": "2025-12-12T10:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
      "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",
      "title": "Managed Service Arbeitsplätze und Microsoft 365",
      "updatedAt": "2026-10-02T08:15:00Z"
    },
    {
      "autoRenew": true,
      "billingCadence": "MONTHLY",
      "contractNumber": "LV-2026-0003",
      "contractType": "SUPPLIER",
      "createdAt": "2025-12-15T08:00:00Z",
      "currency": "EUR",
      "id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a03",
      "netAmount": 79,
      "noticePeriodDays": 30,
      "partnerId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d03",
      "partnerName": "CloudNine Hosting AG",
      "startDate": "2026-01-01T00:00:00Z",
      "status": "ACTIVE",
      "title": "Managed Server kanzlei-srv01",
      "updatedAt": "2025-12-15T08:00:00Z"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI1LTEyLTEyVDEwOjAwOjAwWnwwZTFmMmEzYi00YzVkLTRlNmYtOGE3Yi05YzBkMWUyZjNhMDc"
}
```

### Example request

```bash
curl -X GET 'https://api.mbcom.cloud/api/trade/v1/contracts' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
