openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Payments API
  description: Public REST API for lexoffice, the German cloud accounting and invoicing SaaS from Lexware (Haufe Group), rebranded to "lexware Office" in 2025. The API lets developers push and pull business data - contacts, invoices, quotations, order confirmations, delivery notes, credit notes, dunnings, bookkeeping vouchers, files, payments, and profile metadata - and subscribe to webhooks through event subscriptions. All requests are authenticated with a Bearer API key generated by the account owner at https://app.lexware.de/addons/public-api. The API is rate limited to 2 requests per second per client (HTTP 429 on exceed). The API gateway moved from api.lexoffice.io to api.lexware.io on 26 May 2025; the legacy host remained available through December 2025. This document is a representative, hand-authored subset grounded in the public documentation at https://developers.lexware.io/docs/ - it is not the vendor's own machine-readable specification.
  version: '1.0'
  contact:
    name: lexware Office Developers
    url: https://developers.lexware.io/docs/
  license:
    name: Proprietary
    url: https://www.lexware.de/
servers:
- url: https://api.lexware.io/v1
  description: Lexware API gateway (current)
- url: https://api.lexoffice.io/v1
  description: Legacy lexoffice API gateway (retired end of 2025)
security:
- bearerAuth: []
tags:
- name: Payments
  description: Payment status for a voucher and payment conditions.
paths:
  /payments/{voucherId}:
    parameters:
    - name: voucherId
      in: path
      required: true
      description: The UUID of the voucher whose payment status is requested.
      schema:
        type: string
        format: uuid
    get:
      operationId: getPayments
      tags:
      - Payments
      summary: Retrieve payment status for a voucher
      description: Returns the open amount, payment status, and recorded payment items for a given voucher (invoice, credit note, etc.).
      responses:
        '200':
          description: Payment status for the voucher.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payments'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /payment-conditions:
    get:
      operationId: listPaymentConditions
      tags:
      - Payments
      summary: List payment conditions
      description: Returns the payment conditions (terms and cash discounts) configured in the account.
      responses:
        '200':
          description: A list of payment conditions.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PaymentCondition'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Payments:
      type: object
      properties:
        openAmount:
          type: number
        currency:
          type: string
          example: EUR
        paymentStatus:
          type: string
          enum:
          - open
          - unpaid
          - paidoff
          - voided
        voucherType:
          type: string
        voucherStatus:
          type: string
        paidDate:
          type: string
          format: date-time
        paymentItems:
          type: array
          items:
            type: object
            properties:
              amount:
                type: number
              currency:
                type: string
              paymentItemType:
                type: string
              postingDate:
                type: string
                format: date-time
    Error:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: integer
        error:
          type: string
        path:
          type: string
        message:
          type: string
        details:
          type: array
          items:
            type: object
            properties:
              violation:
                type: string
              field:
                type: string
              message:
                type: string
    PaymentCondition:
      type: object
      properties:
        id:
          type: string
          format: uuid
        paymentTermLabel:
          type: string
        paymentTermDuration:
          type: integer
        paymentDiscountConditions:
          type: object
          properties:
            discountPercentage:
              type: number
            discountRange:
              type: integer
        organizationDefault:
          type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid Bearer API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer API key generated by the account owner at https://app.lexware.de/addons/public-api and passed as `Authorization: Bearer YOUR_API_KEY`.'