Get details of an Invoice

GET/invoices/{invoiceId}/

API version

v2

Request method

GET

Operation ID

invoice-detail

---

Request

• invoiceIdstring (uuid)

  required
  Example:"154219e9-bf4a-4f41-9c72-0449a98db62f"

Responses

Format

application/json

Description

Schema documentation

• 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-11-23T00:28:25.672Z",
    "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-11-23T00:28:25.672Z",
  "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-11-23T00:28:25.672Z",
          "servicePeriod": {
            "end": "2024-11-23T00:28:25.672Z",
            "start": "2024-11-23T00:28:25.672Z"
          },
          "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

{
  "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"
}

Usage examples

cURL

$ curl \
    --fail \
    --location \
    -H "Authorization: Bearer $MITTWALD_API_TOKEN" \
    https://api.mittwald.de/v2/invoices/f0f86186-0a5a-45b2-aa33-502777496347

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.invoiceDetail({
  "invoiceId": "f0f86186-0a5a-45b2-aa33-502777496347"
});

assertStatus(response, 200);
  

PHP SDK

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

$request = (new InvoiceDetailRequest(
  invoiceId: "f0f86186-0a5a-45b2-aa33-502777496347"
));
$response = $client->contract()->invoiceDetail($request);

var_dump($response->getBody();