List Invoices of a Customer

GET/customers/{customerId}/invoices/

API version

v2

Request method

GET

Operation ID

invoice-list-customer-invoices

---

Request

• customerIdstring

  required
  Example:"ac3c8bbe-4c44-4f34-b6c7-1e6af48c3a7c"

Responses

Response headers

• X-Pagination-Limitnumber

  The limit used to select the resources for the response

• X-Pagination-Skipnumber

  The number of skipped items

• X-Pagination-Pagenumber

  The calculate page of the list response. Refer to parameters to learn more.

• X-Pagination-TotalCountnumber

  The total amount of items available in the remote ressource. Use this value in combination with the limit to calculate the available pages.

Format

application/json

Description

Schema documentation

• Array[
• *object
  • amountPaidnumber

    required
  • cancellationobject
    • cancellationIdstring (uuid)

      required
    • cancelledAtstring (date-time)

      required
    • correctionNumberstring

      required
    • pdfIdstring (uuid)

      required
    • reasonstring
  • cancellationOfstring (uuid)

    The ID of the invoice that this invoice cancels.

  • currencystring

    required
  • customerIdstring

    required
  • datestring (date-time)

    required
  • groupsarray of object

    required
    • Array[
    • *object
      • contractIdstring (uuid)
      • descriptionstring
      • itemsarray of object

        required
        • Array[
        • *object
          • additionalDescriptionstring
          • contractItemIdstring (uuid)

            required
          • descriptionstring

            required
          • itemCancelledOrCorrectedByarray of object
            • Array[
            • *object
              • sourceInvoiceIdstring (uuid)
              • sourceInvoiceItemIdstring (uuid)
            ]
        • itemIdstring (uuid)

          required
        • priceobject

          required
          • currency"EUR"

            required
          • valueinteger

            required
        • referenceobject
          • sourceInvoiceIdstring (uuid)

            required
          • sourceInvoiceItemIdstring (uuid)

            required
        • serviceDatestring (date-time)
        • servicePeriodobject
          • endstring (date-time)

            required
          • startstring (date-time)

            required
        • vatRatenumber

          required
      ]
]

idstring (uuid)

required

invoiceNumberstring

required

invoiceTypestring (one of: REGULAR, REISSUE, CORRECTION, CANCELLATION)

required

paymentSettingsone of 2 alternatives

pdfIdstring (uuid)

required

recipientobject

required

• addressobject

  required
  • streetstring

    required
  • houseNumberstring

    required
  • citystring

    required
  • zipstring

    required
  • countryCodestring

    required

    ISO 3166-1 alpha-2 country code

  • addressPrefixstring
• companystring
• emailAddressstring (email)
• firstNamestring
• lastNamestring
• phoneNumbersarray of string
  • Array[
  • *string
  ]

salutationstring (one of: mr, ms, other)

required

titlestring

useFormalTermboolean

statusstring (one of: NEW, CONFIRMED, DENIED, PAID, PARTIALLY_PAID, OVERPAID)

required

totalGrossnumber

required

totalNetnumber

required

vatIdstring

]

Example

[
  {
    "amountPaid": 500,
    "cancellation": {
      "cancellationId": "f0f86186-0a5a-45b2-aa33-502777496347",
      "cancelledAt": "2024-12-03T00:30:29.113Z",
      "correctionNumber": "RG1234567",
      "pdfId": "f0f86186-0a5a-45b2-aa33-502777496347",
      "reason": "Kulanz"
    },
    "cancellationOf": "f0f86186-0a5a-45b2-aa33-502777496347",
    "currency": "EUR",
    "customerId": "e0a3b0e0-0e0e-0e0e-0e0e-0e0e0e0e0e0e",
    "date": "2024-12-03T00:30:29.113Z",
    "groups": [
      {
        "contractId": "f0f86186-0a5a-45b2-aa33-502777496347",
        "description": "Space-Server: \"Mein Space-Server\"",
        "items": [
          {
            "additionalDescription": "Short-ID: \"s-123456\"",
            "contractItemId": "f0f86186-0a5a-45b2-aa33-502777496347",
            "description": "Space-Server: \"Mein Space-Server\"",
            "itemCancelledOrCorrectedBy": [
              {
                "sourceInvoiceId": "f0f86186-0a5a-45b2-aa33-502777496347",
                "sourceInvoiceItemId": "f0f86186-0a5a-45b2-aa33-502777496347"
              }
            ],
            "itemId": "f0f86186-0a5a-45b2-aa33-502777496347",
            "price": {
              "currency": "EUR",
              "value": 1000
            },
            "reference": {
              "sourceInvoiceId": "f0f86186-0a5a-45b2-aa33-502777496347",
              "sourceInvoiceItemId": "f0f86186-0a5a-45b2-aa33-502777496347"
            },
            "serviceDate": "2024-12-03T00:30:29.113Z",
            "servicePeriod": {
              "end": "2024-12-03T00:30:29.113Z",
              "start": "2024-12-03T00:30:29.113Z"
            },
            "vatRate": 19
          }
        ]
      }
    ],
    "id": "f0f86186-0a5a-45b2-aa33-502777496347",
    "invoiceNumber": "RG1234567",
    "invoiceType": "REGULAR",
    "paymentSettings": {
      "accountHolder": "Ada Lovelace",
      "bic": "DEUTDEDB123",
      "iban": "DE12345678901234567890",
      "method": "debit"
    },
    "pdfId": "f0f86186-0a5a-45b2-aa33-502777496347",
    "recipient": {
      "address": {
        "street": "Königsberger Straße",
        "houseNumber": "4-6",
        "city": "Espelkamp",
        "zip": "32339",
        "countryCode": "DE",
        "addressPrefix": "c/o Ada Lovelace"
      },
      "company": "Mittwald CM Service GmbH & Co. KG",
      "emailAddress": "email@mittwald.example",
      "firstName": "Ada",
      "lastName": "Lovelace",
      "phoneNumbers": [
        "+49 123 4567890"
      ],
      "salutation": "mr",
      "title": "Dr.",
      "useFormalTerm": true
    },
    "status": "NEW",
    "totalGross": 595,
    "totalNet": 500,
    "vatId": "DE123456789"
  }
]

JSON Schema

{
  "items": {
    "properties": {
      "amountPaid": {
        "example": 500,
        "type": "number"
      },
      "cancellation": {
        "properties": {
          "cancellationId": {
            "format": "uuid",
            "type": "string"
          },
          "cancelledAt": {
            "format": "date-time",
            "type": "string"
          },
          "correctionNumber": {
            "example": "RG1234567",
            "type": "string"
          },
          "pdfId": {
            "format": "uuid",
            "type": "string"
          },
          "reason": {
            "example": "Kulanz",
            "type": "string"
          }
        },
        "required": [
          "pdfId",
          "correctionNumber",
          "cancelledAt",
          "cancellationId"
        ],
        "type": "object"
      },
      "cancellationOf": {
        "description": "The ID of the invoice that this invoice cancels.",
        "format": "uuid",
        "type": "string"
      },
      "currency": {
        "example": "EUR",
        "type": "string"
      },
      "customerId": {
        "example": "e0a3b0e0-0e0e-0e0e-0e0e-0e0e0e0e0e0e",
        "type": "string"
      },
      "date": {
        "format": "date-time",
        "type": "string"
      },
      "groups": {
        "items": {
          "properties": {
            "contractId": {
              "format": "uuid",
              "type": "string"
            },
            "description": {
              "example": "Space-Server: \"Mein Space-Server\"",
              "type": "string"
            },
            "items": {
              "items": {
                "properties": {
                  "additionalDescription": {
                    "example": "Short-ID: \"s-123456\"",
                    "type": "string"
                  },
                  "contractItemId": {
                    "format": "uuid",
                    "type": "string"
                  },
                  "description": {
                    "example": "Space-Server: \"Mein Space-Server\"",
                    "type": "string"
                  },
                  "itemCancelledOrCorrectedBy": {
                    "items": {
                      "properties": {
                        "sourceInvoiceId": {
                          "format": "uuid",
                          "type": "string"
                        },
                        "sourceInvoiceItemId": {
                          "format": "uuid",
                          "type": "string"
                        }
                      },
                      "type": "object"
                    },
                    "type": "array"
                  },
                  "itemId": {
                    "format": "uuid",
                    "type": "string"
                  },
                  "price": {
                    "properties": {
                      "currency": {
                        "enum": [
                          "EUR"
                        ],
                        "type": "string"
                      },
                      "value": {
                        "example": 1000,
                        "type": "integer"
                      }
                    },
                    "required": [
                      "value",
                      "currency"
                    ],
                    "type": "object"
                  },
                  "reference": {
                    "properties": {
                      "sourceInvoiceId": {
                        "format": "uuid",
                        "type": "string"
                      },
                      "sourceInvoiceItemId": {
                        "format": "uuid",
                        "type": "string"
                      }
                    },
                    "required": [
                      "sourceInvoiceId",
                      "sourceInvoiceItemId"
                    ],
                    "type": "object"
                  },
                  "serviceDate": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "servicePeriod": {
                    "properties": {
                      "end": {
                        "format": "date-time",
                        "type": "string"
                      },
                      "start": {
                        "format": "date-time",
                        "type": "string"
                      }
                    },
                    "required": [
                      "start",
                      "end"
                    ],
                    "type": "object"
                  },
                  "vatRate": {
                    "example": 19,
                    "type": "number"
                  }
                },
                "required": [
                  "itemId",
                  "price",
                  "vatRate",
                  "contractItemId",
                  "description"
                ],
                "type": "object"
              },
              "type": "array"
            }
          },
          "required": [
            "items"
          ],
          "type": "object"
        },
        "type": "array"
      },
      "id": {
        "format": "uuid",
        "type": "string"
      },
      "invoiceNumber": {
        "example": "RG1234567",
        "type": "string"
      },
      "invoiceType": {
        "enum": [
          "REGULAR",
          "REISSUE",
          "CORRECTION",
          "CANCELLATION"
        ],
        "type": "string"
      },
      "paymentSettings": {
        "oneOf": [
          {
            "properties": {
              "accountHolder": {
                "example": "Ada Lovelace",
                "type": "string"
              },
              "bic": {
                "description": "Optional. Required for payments outside of the European Union.",
                "example": "DEUTDEDB123",
                "type": "string"
              },
              "iban": {
                "example": "DE12345678901234567890",
                "type": "string"
              },
              "method": {
                "enum": [
                  "debit"
                ],
                "type": "string"
              }
            },
            "required": [
              "method",
              "iban",
              "accountHolder"
            ],
            "type": "object"
          },
          {
            "properties": {
              "method": {
                "enum": [
                  "invoice"
                ],
                "type": "string"
              }
            },
            "required": [
              "method"
            ],
            "type": "object"
          }
        ]
      },
      "pdfId": {
        "format": "uuid",
        "type": "string"
      },
      "recipient": {
        "properties": {
          "address": {
            "type": "object",
            "properties": {
              "street": {
                "type": "string",
                "example": "Königsberger Straße"
              },
              "houseNumber": {
                "type": "string",
                "example": "4-6"
              },
              "city": {
                "type": "string",
                "example": "Espelkamp"
              },
              "zip": {
                "type": "string",
                "example": "32339"
              },
              "countryCode": {
                "type": "string",
                "example": "DE",
                "description": "ISO 3166-1 alpha-2 country code"
              },
              "addressPrefix": {
                "type": "string",
                "example": "c/o Ada Lovelace"
              }
            },
            "required": [
              "street",
              "houseNumber",
              "city",
              "zip",
              "countryCode"
            ]
          },
          "company": {
            "example": "Mittwald CM Service GmbH & Co. KG",
            "type": "string"
          },
          "emailAddress": {
            "format": "email",
            "type": "string"
          },
          "firstName": {
            "example": "Ada",
            "type": "string"
          },
          "lastName": {
            "example": "Lovelace",
            "type": "string"
          },
          "phoneNumbers": {
            "items": {
              "example": "+49 123 4567890",
              "type": "string"
            },
            "type": "array"
          },
          "salutation": {
            "type": "string",
            "enum": [
              "mr",
              "ms",
              "other"
            ]
          },
          "title": {
            "example": "Dr.",
            "type": "string"
          },
          "useFormalTerm": {
            "type": "boolean"
          }
        },
        "required": [
          "address",
          "salutation"
        ],
        "type": "object"
      },
      "status": {
        "enum": [
          "NEW",
          "CONFIRMED",
          "DENIED",
          "PAID",
          "PARTIALLY_PAID",
          "OVERPAID"
        ],
        "type": "string"
      },
      "totalGross": {
        "example": 595,
        "type": "number"
      },
      "totalNet": {
        "example": 500,
        "type": "number"
      },
      "vatId": {
        "example": "DE123456789",
        "type": "string"
      }
    },
    "required": [
      "id",
      "customerId",
      "invoiceNumber",
      "date",
      "pdfId",
      "groups",
      "status",
      "amountPaid",
      "recipient",
      "totalNet",
      "totalGross",
      "currency",
      "invoiceType"
    ],
    "type": "object"
  },
  "type": "array"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/customers/string/invoices?invoiceTypes=REGULAR&limit=50&page=1

JavaScript SDK

import { MittwaldAPIV2Client } from "@mittwald/api-client";
import { assertStatus } from "@mittwald/api-client-commons";
  
const client = MittwaldAPIClient.newWithToken(process.env.MITTWALD_API_TOKEN);
const response = await client.contract.invoiceListCustomerInvoices({
  "customerId": "string",
  "queryParameters": {
    "invoiceTypes": [
      "REGULAR"
    ],
    "limit": 50,
    "page": 1
  }
});

assertStatus(response, 200);
  

PHP SDK

use \Mittwald\ApiClient\Generated\V2\Clients\Contract\InvoiceListCustomerInvoices\InvoiceListCustomerInvoicesRequest;
  
$client = MittwaldAPIClient::newWithToken(getenv('MITTWALD_API_TOKEN'));

$request = (new InvoiceListCustomerInvoicesRequest(
  customerId: "string"
))
  ->withInvoiceTypes(["REGULAR"])
  ->withLimit(50)
  ->withPage(1);
$response = $client->contract()->invoiceListCustomerInvoices($request);

var_dump($response->getBody();