## List inbound invoices (tenant:trade:inbound:read)

`GET /api/trade/v1/inbound-invoices`

Module: Trade · operationId: `listInboundInvoices` · Tag: Inbound invoices · Auth: access token (`Authorization: Bearer <accessToken>`)

Newest first (creation time, then id), without OCR text and lines; pages by keyset (`nextCursor`), `total` counts all matches.

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `status` | query | string |  | One status or a comma-separated list (case-insensitive), e.g. `MATCHED,DISCREPANCY`. |
| `q` | query | string |  | Substring of the internal number, the supplier's invoice number or the supplier name. |
| `limit` | query | integer |  | 1–200 (else `400 invalid`). (default `50`; max 200) |
| `cursor` | query | string |  | The `nextCursor` of the previous page; omit for the first page. A cursor of another list is `400 invalid`. |

### Responses

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

Fields of the 200 answer:

- `items` (array of InboundInvoice, required): The inbound invoices of the page.
  - `addressSnapshot` (object): The supplier as read (`extracted`) and as assigned from master data (`supplier`, `assignment`), and the VAT ID check of the assigned supplier (`vatCheck`).
    - `assignment` (object): How the supplier was assigned (method, confidence, evidence).
    - `extracted` (object): The supplier as read from the document.
    - `supplier` (object): The assigned master data supplier.
    - `vatCheck` (object): Simple (VIES) check of the assigned supplier's master data VAT ID, run through master data when the supplier is assigned (a repeat within 24 hours answers from the master data cache). Informational: it never blocks the invoice. Missing when the supplier has no VAT ID or the check could not be run; it is replaced when another supplier is assigned.
      - `cached` (boolean): The result came from the 24-hour cache of master data.
      - `checkedAt` (string (date-time)): When the VAT id was checked.
      - `method` (string): How the VAT id was checked. (one of `VIES`, `BZST`)
      - `serviceUnavailable` (boolean): VIES or the member state could not be reached; check again later.
      - `status` (string): Outcome of the VAT id check. (one of `OFFICIALLY_CONFIRMED`, `PARTIALLY_CONFIRMED`, `OFFICIALLY_NOT_CONFIRMED`, `FORMALLY_VALID_NO_OFFICIAL_CHECK`, `FORMALLY_INVALID`, `CHECK_NOT_POSSIBLE`, `TECHNICAL_ERROR`)
      - `statusDisplay` (string): The status as German text.
      - `statusMessage` (string): Message of the checking service, if any.
      - `vatId` (string): VAT id checked.
  - `autoRelease` (AutoReleaseDecision): Verdict of the automatic release on an inbound invoice, stored whenever the mode is not `off`. A person's re-check (match, update) stores a fresh verdict that is not eligible (the person touched the invoice); a person's release or rejection removes it.
    - `eligible` (boolean): Every condition holds.
    - `evaluatedAt` (string (date-time)): When the decision was evaluated.
    - `mode` (string): Mode of the automatic release when the verdict was made (`off`, `dryRun`, `on`). (one of `off`, `dryRun`, `on`)
    - `reasons` (array of string): Each failed condition (German text).
    - `released` (boolean): The system released the invoice (mode `on`); false again after a reopen.
    - `rule` (string): The rule that applied, also the protocol note of the release.
    - `suppressed` (boolean): The release was reopened; the invoice is never released automatically again.
  - `createdAt` (string (date-time)): When the inbound invoice was created.
  - `currency` (string): Currency (ISO 4217).
  - `customerNo` (string): Customer number of the tenant.
  - `deliveryDate` (string (date)): Delivery date.
  - `dmsDocumentId` (string (uuid)): DMS document of the invoice.
  - `dueDate` (string (date)): Due date.
  - `duplicateOf` (string (uuid)): The invoice this one duplicates (lock reason `DUPLIKAT`).
  - `error` (string): Why processing failed (status `FAILED`).
  - `exchangeRate` (number): Exchange rate to EUR.
  - `extraction` (Extraction): What the e-invoice or the OCR/AI extraction delivered; written once.
    - `confidence` (object): Per field (AI extraction only).
    - `creditorId` (string): SEPA creditor identifier of the supplier (BT-90); e-invoices only.
    - `currency` (string): Currency (ISO 4217).
    - `customerNumber` (string): Our customer number at the supplier.
    - `deliveryDate` (string): Delivery date (YYYY-MM-DD).
    - `deliveryNoteNumber` (string): Delivery note number stated on the invoice.
    - `discountTerms` (array of object): Cash discount terms.
      - `days` (integer): Days within which the discount applies.
      - `percent` (number): Discount in percent.
    - `discountText` (string): Cash discount terms as printed.
    - `documentType` (string): Document type read from the document. (one of `380`, `381`, `384`, `999`)
    - `documentTypeCode` (string): BT-3 code as stated in the e-invoice.
    - `dueDate` (string): Due date (YYYY-MM-DD).
    - `grossTotal` (number): Gross total.
    - `invoiceDate` (string (date)): Invoice date (YYYY-MM-DD).
    - `invoiceNumber` (string): Invoice number.
    - `isReverseCharge` (boolean): The invoice is reverse charge.
    - `lines` (array of InboundInvoiceLine): Lines read from the document.
    - `mandateReference` (string): SEPA direct debit mandate reference (BT-89); e-invoices only.
    - `netDays` (integer): Days until the net amount is due.
    - `netTotal` (number): Net total.
    - `notes` (string): Document notes of an e-invoice (BT-22, one per line), or the notes of the AI extraction.
    - `orderNumber` (string): Order number stated on the invoice.
    - `payerIban` (string): IBAN of the account the supplier debits (BT-91), without spaces; e-invoices only.
    - `paymentMeansCode` (string): Payment means code (BT-81, UNTDID 4461), e.g. `58` SEPA credit transfer, `59` SEPA direct debit; e-invoices only.
    - `paymentMeansText` (string): Payment means as text (BT-82); e-invoices only.
    - `paymentText` (string): Payment terms as stated (BT-20 for e-invoices), HTML entities decoded.
    - `recipient` (Party)
    - `servicePeriodEnd` (string (date)): End of the invoiced service period (BT-74); e-invoices only.
    - `servicePeriodStart` (string (date)): Start of the invoiced service period (BT-73); e-invoices only.
    - `sourceKind` (string): How it was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
    - `taxExemptionReason` (string): Stated reason for a tax exemption.
    - `taxRates` (array of object): Tax breakdown per rate.
      - `netAmount` (number): Net amount taxed at the rate.
      - `rate` (number): Tax rate in percent.
      - `taxAmount` (number): Tax amount at the rate.
    - `taxTotal` (number): Tax total.
    - `vendor` (Party)
  - `fullText` (string): OCR text (single invoice only).
  - `id` (string (uuid)): Id of the inbound invoice.
  - `invoiceDate` (string (date)): Invoice date.
  - `invoiceNumber` (string): The supplier's invoice number.
  - `lineItems` (array of InboundInvoiceLine): Lines of the invoice.
    - `articleAssignment` (object): How the article was resolved.
      - `confidence` (number): Confidence of the article assignment (0–1).
      - `evidence` (string): What the article assignment is based on.
      - `method` (string): How the article was found: `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback` or `manual`. (one of `exact_vat`, `exact_iban`, `exact_number`, `supplier_number`, `semantic`, `llm`, `fallback`, `manual`)
    - `articleNumber` (string): Internal article number (masterdata).
    - `description` (string): Description of the line.
    - `ean` (string): EAN (GTIN) of the article.
    - `ignored` (boolean): Article on the configured ignore list.
    - `mpn` (string): Manufacturer part number.
    - `netAmount` (number): Net amount of the line.
    - `orderLineRef` (string): Order line the line refers to (BT-132).
    - `orderNumber` (string): Order number the line refers to.
    - `position` (integer): Position number of the line.
    - `productId` (string): Masterdata article (product) id.
    - `quantity` (number): Quantity.
    - `taxRate` (number): Tax rate in percent.
    - `unit` (string): Unit of measure.
    - `unitPrice` (number): Net unit price.
    - `vendorArticleNo` (string): The supplier's article number.
  - `lockReasons` (array of LockReason): Why the invoice may not be released as it is.
    - `article` (string): Article of the line.
    - `code` (string): E.g. `PREISABWEICHUNG`, `MENGENABWEICHUNG`, `DUPLIKAT`, `FEHLENDER_LIEFERANT`, `FEHLENDER_ARTIKEL`, `KEINE_E_RECHNUNG`, `NIEDRIGE_KONFIDENZ`, `EMPFAENGER_ABWEICHUNG`, `LIEFERANT_GESPERRT` (the supplier is blocked or payment-blocked in masterdata), `FEHLENDE_BESTELLUNG`, `BESTELLUNG_NICHT_GEFUNDEN`, `EGIS_ABWEICHUNG` (amounts differ from the distributor's invoice data in EGIS).
    - `description` (string): Human-readable explanation.
    - `isBlocking` (boolean): The reason blocks the release until it is accepted or overridden.
    - `position` (integer): Line position the reason refers to; 0 for the whole invoice.
    - `variance` (number): Variance found (amount or quantity).
  - `matchResult` (MatchResult)
    - `evaluatedAt` (string (date-time)): When the match ran.
    - `isBlocked` (boolean): A blocking lock reason was found.
    - `isMatched` (boolean): The invoice matches the purchase order within the tolerances.
    - `lockReasons` (array of LockReason): Lock reasons found.
    - `matchedLines` (array of object): Result per invoice line.
      - `articleNumber` (string): Article number in masterdata.
      - `availableQty` (number): Received minus already invoiced.
      - `description` (string): Description of the line.
      - `invoicePosition` (integer): Position on the invoice.
      - `invoicedPrice` (number): Unit price invoiced.
      - `invoicedQty` (number): Quantity invoiced.
      - `isMatched` (boolean): The line matches within the tolerances.
      - `poPosition` (integer): Position on the purchase order.
      - `poPrice` (number): Unit price ordered.
      - `poQty` (number): Quantity ordered.
      - `priceVariance` (number): Unit price variance.
      - `qtyVariance` (number): Quantity variance.
      - `receivedQty` (number): Quantity received.
      - `varianceType` (string): `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED` or `UNKNOWN_POSITION`. (one of `NONE`, `PRICE`, `QUANTITY`, `BOTH`, `NOT_RECEIVED`, `UNKNOWN_POSITION`)
    - `status` (string): `matched`, `variance_detected`, `blocked`, `unmatched` or `not_required`. (one of `matched`, `variance_detected`, `blocked`, `unmatched`, `not_required`)
    - `totalVariance` (number): Sum of the price variances.
  - `matchingStatus` (string): Match status, `blocked`, or `not_applicable` for credit notes and corrections.
  - `netDays` (integer): Days until the net amount is due, as stated (or parsed from the payment text).
  - `netTotal` (number): Net total.
  - `partnerReference` (string): Our order number as printed on the invoice.
  - `paymentTermsText` (string): Payment terms as printed text.
  - `processing` (object): The step a pipeline run is in right now – each waits for another service; missing when no run is going on.
    - `startedAt` (string (date-time)): When the current processing started.
    - `step` (string): `queued` started, `text` loading the DMS text, `classify` and `extract` the AI service (or reading the e-invoice), `evaluate` assignments, checks and purchase order match. (one of `queued`, `text`, `classify`, `extract`, `evaluate`)
  - `purchaseOrderId` (string (uuid)): Purchase order the invoice is matched against.
  - `resolvedLockReasons` (array of object): Blocking lock reasons a person accepted (cleared when the document is read anew).
    - `code` (string): Code of the lock reason.
    - `comment` (string): Why it was accepted.
    - `position` (integer): Line position the lock reason refers to; 0 for the whole invoice.
    - `resolvedAt` (string (date-time)): When it was accepted.
    - `resolvedBy` (string): Who accepted it.
  - `skontoDays1` (integer): Days of the first cash discount.
  - `skontoDays2` (integer): Days of the second cash discount.
  - `skontoRate1` (number): Rate in percent of the first cash discount.
  - `skontoRate2` (number): Rate in percent of the second cash discount.
  - `skontoTerms` (any): Cash discount terms.
  - `sourceKind` (string): How the invoice was read (e-invoice XML or OCR and AI extraction). (one of `XRECHNUNG_CII`, `XRECHNUNG_UBL`, `ZUGFERD`, `PDF_OCR`)
  - `status` (InboundInvoiceStatus): (one of `RECEIVED`, `OCR_DONE`, `EXTRACTED`, `MATCHED`, `DISCREPANCY`, `IN_REVIEW`, `RELEASED`, `REJECTED`, `DUPLICATE`, `FAILED`)
  - `supplierAddressId` (string (uuid)): Masterdata address of the supplier.
  - `taxTotal` (number): Tax total.
  - `tenantName` (string): Name of the tenant.
  - `totalAmount` (number): Gross total of the invoice.
  - `totalAmountEur` (number): Gross total in EUR (ECB rate).
  - `transactionNumber` (string): Internal number.
  - `transactionType` (string): `INBOUND_INVOICE` or the IN type with the e-invoice code of the document.
  - `updatedAt` (string (date-time)): When the inbound invoice was last changed.
  - `validationReport` (object): E-invoice check of the XML, when the invoice is an e-invoice.
  - `validationStatus` (string): Result of the formal (UStG §14) validation; `pending` until validated.
  - `vendorName` (string): Name of the supplier as stated on the invoice.
  - `vendorVatId` (string): Manual correction of the supplier's VAT ID.
- `total` (integer, required): Number of entries of the whole list.
- `nextCursor` (string): Pass as `cursor` for the next page; absent on the last one.

Example 200 answer:

```json
{
  "items": [
    {
      "createdAt": "2026-10-26T08:35:00Z",
      "currency": "EUR",
      "dueDate": "2026-11-22",
      "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a02",
      "invoiceDate": "2026-10-23",
      "invoiceNumber": "RE-483350",
      "matchingStatus": "blocked",
      "netTotal": 4347,
      "sourceKind": "XRECHNUNG_CII",
      "status": "DISCREPANCY",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "taxTotal": 825.93,
      "totalAmount": 5172.93,
      "transactionNumber": "ER-2026-00036",
      "transactionType": "INBOUND_INVOICE",
      "updatedAt": "2026-10-26T08:36:02Z",
      "vendorName": "Nordlicht IT-Distribution GmbH"
    },
    {
      "createdAt": "2026-10-05T08:40:00Z",
      "currency": "EUR",
      "dueDate": "2026-11-01",
      "id": "8e1f2a3b-4c5d-4e6f-9a7b-0c1d2e3f4a01",
      "invoiceDate": "2026-10-02",
      "invoiceNumber": "RE-482117",
      "matchingStatus": "matched",
      "netTotal": 5808,
      "sourceKind": "XRECHNUNG_CII",
      "status": "MATCHED",
      "supplierAddressId": "6d8f0a12-3c4e-4a5b-9d6f-7e8a9b0c1d01",
      "taxTotal": 1103.52,
      "totalAmount": 6911.52,
      "transactionNumber": "ER-2026-00031",
      "transactionType": "INBOUND_INVOICE",
      "updatedAt": "2026-10-05T08:41:12Z",
      "vendorName": "Nordlicht IT-Distribution GmbH"
    }
  ],
  "nextCursor": "Y3JlYXRlZHwyMDI2LTEwLTA1VDA4OjQwOjAwWnw4ZTFmMmEzYi00YzVkLTRlNmYtOWE3Yi0wYzFkMmUzZjRhMDE",
  "total": 14
}
```

### Example request

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