openapi: 3.0.3
info:
  title: lexoffice (lexware Office) Public Contacts Credit Notes 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: Credit Notes
  description: Credit note documents.
paths:
  /credit-notes:
    post:
      operationId: createCreditNote
      tags:
      - Credit Notes
      summary: Create a credit note
      parameters:
      - name: finalize
        in: query
        required: false
        schema:
          type: boolean
          default: false
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SalesDocument'
      responses:
        '201':
          description: Reference to the created credit note.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceReference'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credit-notes/{id}:
    parameters:
    - $ref: '#/components/parameters/Id'
    get:
      operationId: getCreditNote
      tags:
      - Credit Notes
      summary: Retrieve a credit note
      responses:
        '200':
          description: The requested credit note.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SalesDocument'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Id:
      name: id
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
        format: uuid
  schemas:
    TotalPrice:
      type: object
      properties:
        currency:
          type: string
          example: EUR
        totalNetAmount:
          type: number
        totalGrossAmount:
          type: number
        totalTaxAmount:
          type: number
    LineItem:
      type: object
      properties:
        id:
          type: string
          format: uuid
        type:
          type: string
          enum:
          - custom
          - material
          - service
          - text
        name:
          type: string
        description:
          type: string
        quantity:
          type: number
        unitName:
          type: string
        unitPrice:
          type: object
          properties:
            currency:
              type: string
              example: EUR
            netAmount:
              type: number
            grossAmount:
              type: number
            taxRatePercentage:
              type: number
        discountPercentage:
          type: number
        lineItemAmount:
          type: number
    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
    ResourceReference:
      type: object
      properties:
        id:
          type: string
          format: uuid
        resourceUri:
          type: string
          format: uri
        createdDate:
          type: string
          format: date-time
        updatedDate:
          type: string
          format: date-time
        version:
          type: integer
    SalesDocument:
      type: object
      description: Shared shape for quotation, order confirmation, delivery note, credit note, and dunning documents.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        organizationId:
          type: string
          format: uuid
        version:
          type: integer
        language:
          type: string
          example: de
        archived:
          type: boolean
          readOnly: true
        voucherStatus:
          type: string
          readOnly: true
        voucherNumber:
          type: string
          readOnly: true
        voucherDate:
          type: string
          format: date-time
        address:
          type: object
          properties:
            contactId:
              type: string
              format: uuid
            name:
              type: string
            street:
              type: string
            zip:
              type: string
            city:
              type: string
            countryCode:
              type: string
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        totalPrice:
          $ref: '#/components/schemas/TotalPrice'
        taxConditions:
          $ref: '#/components/schemas/TaxConditions'
        title:
          type: string
        introduction:
          type: string
        remark:
          type: string
    TaxConditions:
      type: object
      properties:
        taxType:
          type: string
          enum:
          - net
          - gross
          - vatfree
          - intraCommunitySupply
          - constructionService13b
          - externalService13b
          - thirdPartyCountryService
          - thirdPartyCountryDelivery
        taxTypeNote:
          type: string
  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`.'