## List the MSP invoices of a month (tenant:trade:msp:read)

`GET /api/trade/v1/msp/invoices`

Module: Trade · operationId: `listMspInvoices` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

One invoice per billed customer address and month, without lines.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `month` | query | string |  | Billing month `YYYY-MM` (Europe/Berlin); default the previous month. |

### Responses

- **200** Invoices (`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`)

Fields of the 200 answer:

- `invoices` (array of MspInvoice)
  - `addressId` (string (uuid)): Masterdata address of the customer.
  - `addressName` (string): Name of the customer.
  - `approvedAt` (string (date-time)): When the invoice was approved.
  - `approvedBy` (string): Who approved the invoice.
  - `attempts` (integer): Number of posting attempts.
  - `computedAt` (string (date-time)): When the draft was computed.
  - `delivery` (MspDelivery): `send`: approving issues the invoice in Verkauf and mails it to the customer; `issue`: it is only issued (final number, XRechnung, the XML in DMS). (one of `send`, `issue`)
  - `error` (string): Why the last posting failed.
  - `id` (string (uuid)): Id of the MSP invoice.
  - `lines` (array of MspInvoiceLine): Positions of the invoice.
    - `articleNumber` (string): Article number in masterdata.
    - `contractId` (string (uuid)): Contract of the position.
    - `contractItemId` (string (uuid)): The contract position of a `fixed` line.
    - `kind` (string): `fixed` (a contract item) or `usage` (collected usage). (one of `fixed`, `usage`)
    - `name` (string): Name printed on the invoice position.
    - `position` (integer): Position number of the line.
    - `problem` (string): Why the position cannot be billed as it is.
    - `provider` (string): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …).
    - `quantity` (number): Quantity.
    - `sourceSku` (string): The provider's SKU.
    - `text` (string): Printed below the name; missing when none. ITC: `VM: <name>` of the virtual machine.
    - `total` (number): Net total of the position.
    - `unitPrice` (number): Missing when no price is known (a problem).
    - `usageItemIds` (array of string (uuid)): The usage items of a `usage` line.
  - `month` (integer): Month (1–12) of the billing month.
  - `netTotal` (number): Net total of the invoice.
  - `postedAt` (string (date-time)): When the invoice was posted.
  - `problems` (array of string): Each blocks the approval (e.g. "Preisänderung für Artikel … wartet auf Freigabe (… → … €)." while a price suggestion of a billed article is open).
  - `stale` (boolean): Usage, a mapping or a contract position changed after the computation: recompute before approving.
  - `status` (string): Status of the MSP invoice (`draft`, `approved`, `posting`, `posted`, `failed`). (one of `draft`, `approved`, `posting`, `posted`, `failed`)
  - `transactionId` (string (uuid)): The booked INVOICE in trade.
  - `transactionNumber` (string): Number of the invoice in Verkauf once posted.
  - `year` (integer): Year of the billing month.
- `month` (integer)
- `year` (integer)

Example 200 answer:

```json
{
  "invoices": [
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c02",
      "addressName": "Kanzlei Hofmann \u0026 Partner Rechtsanwälte mbB",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c01",
      "lines": [
        {
          "articleNumber": "MSFTCFQ7TTC0LDPB0001P1YM",
          "kind": "usage",
          "name": "Microsoft 365 Business Standard 1YM",
          "position": 1,
          "provider": "ingram",
          "quantity": 12,
          "sourceSku": "CFQ7TTC0LDPB:0001/P1YM",
          "total": 150,
          "unitPrice": 12.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c01"
          ]
        },
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 2,
          "provider": "itc",
          "quantity": 4,
          "sourceSku": "7030222",
          "text": "VM: kanzlei-srv01",
          "total": 38,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c11"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 3,
          "provider": "itc",
          "quantity": 16,
          "sourceSku": "7030220",
          "text": "VM: kanzlei-srv01",
          "total": 51.2,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c12"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 4,
          "provider": "itc",
          "quantity": 500,
          "sourceSku": "7030003",
          "text": "VM: kanzlei-srv01",
          "total": 60,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c13"
          ]
        },
        {
          "articleNumber": "DL-9005",
          "contractId": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a07",
          "contractItemId": "1f2a3b4c-5d6e-4f7a-9b8c-0d1e2f3a4b01",
          "kind": "fixed",
          "name": "Supportpauschale Fernwartung, monatlich",
          "position": 5,
          "quantity": 1,
          "total": 180,
          "unitPrice": 180
        }
      ],
      "month": 10,
      "netTotal": 479.2,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    },
    {
      "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c05",
      "addressName": "Donau Maschinenbau AG",
      "attempts": 0,
      "computedAt": "2026-11-03T06:12:00Z",
      "delivery": "send",
      "id": "2a3b4c5d-6e7f-4a8b-9c0d-1e2f3a4b5c02",
      "lines": [
        {
          "articleNumber": "ITC7030222P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server CPU Performance Plus",
          "position": 1,
          "provider": "itc",
          "quantity": 8,
          "sourceSku": "7030222",
          "text": "VM: dmb-erp01",
          "total": 76,
          "unitPrice": 9.5,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c14"
          ]
        },
        {
          "articleNumber": "ITC7030220P1MM",
          "kind": "usage",
          "name": "ITC CLOUD Server RAM 1 GB",
          "position": 2,
          "provider": "itc",
          "quantity": 32,
          "sourceSku": "7030220",
          "text": "VM: dmb-erp01",
          "total": 102.4,
          "unitPrice": 3.2,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c15"
          ]
        },
        {
          "articleNumber": "ITC7030003P1MM",
          "kind": "usage",
          "name": "ITC CLOUD 3 Wege Storage Standard je GB",
          "position": 3,
          "provider": "itc",
          "quantity": 1200,
          "sourceSku": "7030003",
          "text": "VM: dmb-erp01",
          "total": 144,
          "unitPrice": 0.12,
          "usageItemIds": [
            "0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c16"
          ]
        }
      ],
      "month": 10,
      "netTotal": 322.4,
      "problems": [],
      "stale": false,
      "status": "draft",
      "year": 2026
    }
  ],
  "month": 10,
  "year": 2026
}
```

### Example request

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