NAV
cURL

lexoffice API Documentation

This documentation describes the set-up process, where to start with the API and the currently available endpoints. It moreover provides samples and suggestions on how to get the best out of the API.

Introduction

The lexoffice API is a REST API that allows developers to incorporate lexoffice into their applications by pushing and pulling data from and to lexoffice. Examples for this data are contact information and e.g. scanned images for bookkeeping vouchers (referred to as "files"). The responses of the endpoints are formatted in JSON.

The lexoffice API endpoints are exposed by a gateway located at https://api.lexoffice.io. In the request examples throughout this documentation, we use placeholder variables {appbaseurl} to refer to the lexoffice application url, {resourceurl} to refer to the resource urls of the lexoffice API endpoints and {accessToken} to refer to the API key. We also use access token and API key interchangeably.

Users of the lexoffice API can generate their private API key at https://app.lexoffice.de/settings/#/public-api.

Additionally to this reference documentation, various cookbooks – lexoffice API Kochbücher – are available in German. They describe the concepts of aspects of the API from a high level perspective and are helpful as recipes for the implementation of lexoffice integrations.

Contacts Endpoint

Purpose

This endpoint provides read access to contacts (e.g. customers, vendors). A contact can hold addresses, contact information (e.g. phone numbers, email addresses) and contact persons for company related contacts. It is also possible to use filters on the contacts collection.

Contact Properties

Sample of a contact with roles customer and vendor

{
    "id": "be9475f4-ef80-442b-8ab9-3ab8b1a2aeb9",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "version": 1,
    "roles": {
        "customer": {
            "number": 10307
        },
        "vendor": {
            "number": 70303
        }
    },
    "company": {
        "name": "Testfirma",
        "taxNumber": "12345/12345",
        "vatRegistrationId": "DE123456789",
        "allowTaxFreeInvoices": true,
        "contactPersons": [
            {
                "salutation": "Herr",
                "firstName": "Max",
                "lastName": "Mustermann",
                "primary": true,
                "emailAddress": "contactpersonmail@lexoffice.de",
                "phoneNumber": "08000/11111"
            }
        ]
    },
    "addresses": {
        "billing": [
            {
                "supplement": "Rechnungsadressenzusatz",
                "street": "Hauptstr. 5",
                "zip": "12345",
                "city": "Musterort",
                "countryCode": "DE"
            }
        ],
        "shipping": [
            {
                "supplement": "Lieferadressenzusatz",
                "street": "Schulstr. 13",
                "zip": "76543",
                "city": "MUsterstadt",
                "countryCode": "DE"
            }
        ]
    },
    "xRechnung": {
        "buyerReference": "04011000-1234512345-35",
        "vendorNumberAtCustomer": "70123456"
    },
    "emailAddresses": {
        "business": [
            "business@lexoffice.de"
        ],
        "office": [
            "office@lexoffice.de"
        ],
        "private": [
            "private@lexoffice.de"
        ],
        "other": [
            "other@lexoffice.de"
        ]
    },
    "phoneNumbers": {
        "business": [
            "08000/1231"
        ],
        "office": [
            "08000/1232"
        ],
        "mobile": [
            "08000/1233"
        ],
        "private": [
            "08000/1234"
        ],
        "fax": [
            "08000/1235"
        ],
        "other": [
            "08000/1236"
        ]
    },
    "note": "Notizen",
    "archived": false
}
                    Property Description
id
uuid
Unique id of the contact generated on creation by lexoffice.
organizationId
uuid
Unique id of the organization the contact belongs to.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
roles
object
Defines contact roles and supports further contact information. For object details see below.
company
object
Company related information. For details see below.
person
object
Individual person related information. For details see below.
addresses
object
Addresses (e.g. billing and shipping address(es)) for the contact. Contains a list for each address type. For details see below.
xRechnung
object
XRechnung related properties of the contact
emailAddresses
object
Email addresses for the contact. Contains a list for each EMail type. For details see below.
phoneNumbers
object
Phone numbers for the contact. Contains a list for each PhoneNumber type. For details see below.
note
string
A note to the contact. This is just an additional information.
archived
boolean
Archived flag of the contact.
Read-only.

Roles Details

Contains a customer and/or a vendor object. The presence of a role in the JSON implies that the contact will have this role. For example, if the customer object is present, the contact has the role customer. Please note that each contact must have at least one role.

                    Property Description
customer
object
May be present. If present the created contact has the role customer.
vendor
object
May be present. If present the created contact has the role vendor.

Customer Details

                    Property Description
number
integer
Unique customer number within the current organization. This number is created by lexoffice for contacts with role Customer. It cannot be set during creation and cannot be changed.
Read-only.

Vendor Details

                    Property Description
number
integer
Unique vendor number within the current organization. This number is created by lexoffice for contacts with role Vendor. It cannot be set during creation and cannot be changed.
Read-only.



Company Details

Use this object to provide information for a contact of type company.

                    Property Description
allowTaxFreeInvoices
boolean
Possible values are true or false.
name
string
Company name
taxNumber
string
Tax number for this company --> "Steuernummer".
vatRegistrationId
string
Vat registration id for this company. This id has to follow the german rules for the vat registration ids --> "Umsatzsteuer ID".
contactPersons
list
A list of company contact persons. Each entry is an object of company contact person. Details of nested object please see below.

Company Contact Person Details

                    Property Description
salutation
string
Salutation for the contact person with max length of 25 characters.
firstName
string
First name of the contact person.
lastName
string
Last name of the contact person.
primary
boolean
Flags if contact person is the primary contact person. Primary contact persons are shown on vouchers. Default is false.
emailAddress
string
Email address of the contact person.
phoneNumber
string
Phone number of the contact person.



Person Details

Sample json for a contact of type private person

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "version": 0,
  "roles": {
    "customer": {
      "number": 10308
    }
  },
  "person": {
    "salutation": "Frau",
    "firstName": "Inge",
    "lastName": "Musterfrau"
  },
  "archived": false
}

Use this object to provide information for a contact of type private person.

                    Property Description
salutation
string
Salutation for the individual person with max length of 25 characters.
firstName
string
First name of the person.
lastName
string
Last name of the person.



Addresses Details

Use this objects to provide billing and shipping information of a contact.

                    Property Description
billing
list
A list of billing addresses. Each entry is an object of address.
shipping
list
A list of shipping addresses. Each entry is an object of address.

Address Details

                    Property Description
supplement
string
Additional address information.
street
string
Street with Street number.
zip
string
Zip code
city
string
City
countryCode
string
Country code in the format of ISO 3166 alpha2 (e.g. DE is used for germany).



XRechnung Details

If a customer's buyerReference is set, its vendorNumberAtCustomer needs to be set as well.

                    Property Description
buyerReference
string
Customer's Leitweg-ID conforming to the German XRechnung system
vendorNumberAtCustomer
string
Your vendor number as used by the customer



E-Mail Addresses Details

                    Property Description
business
list
A list of email addresses. Each entry is of type string and contains an email address.
office
list
A list of email addresses. Each entry is of type string and contains an email address.
private
list
A list of email addresses. Each entry is of type string and contains an email address.
other
list
A list of email addresses. Each entry is of type string and contains an email address.



Phone Numbers Details

                    Property Description
business
list
A list of phone numbers. Each entry is of type string and contains a phone number.
office
list
A list of phone numbers. Each entry is of type string and contains a phone number.
mobile
list
A list of phone numbers. Each entry is of type string and contains a phone number.
private
list
A list of phone numbers. Each entry is of type string and contains a phone number.
fax
list
A list of phone numbers. Each entry is of type string and contains a phone number.
other
list
A list of phone numbers. Each entry is of type string and contains a phone number.

Create a Contact

Sample Request to create a customer

curl https://api.lexoffice.io/v1/contacts
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
  "version": 0,
  "roles": {
    "customer": {
    }
  },
  "person": {
     "salutation": "Frau",
     "firstName": "Inge",
     "lastName": "Musterfrau"
  },
  "note": "Notizen"
}'

Sample response

{
  "id": "66196c43-baf3-4335-bfee-d610367059db",
  "resourceUri": "https://api.lexoffice.io/v1/contacts/66196c43-bfee-baf3-4335-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/contacts

The contents of the contact are expected in the request’s body as an application/json.

Description of required properties when creating a customer.

                    Property Required Notes
version Yes Set to 0
roles Yes Each customer must have at least one role. The role must be set as an empty object.
company * If the contact is of type company it must be set.
person * If the contact is of type person it must be set.

Company Details

                    Property Required Notes
name Yes Must not be empty if customer is of type company.

Company Contact Person Details

                    Property Required Notes
salutation No Changed to optional (see Change Log).
lastName Yes Must be not empty if customer is of type company.

Person Details

                    Property Required Notes
salutation No Changed to optional (see Change Log).
lastName Yes Must be not empty if customer is of type person.

Address Details

                    Property Required Notes
countryCode Yes Must be not empty. Must contain the country code in the format of ISO 3166 alpha2 (e.g. DE is used for germany).

Retrieve a Contact

Sample request

curl https://api.lexoffice.io/v1/contacts/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "version": 0,
  "roles": {
    "customer": {
      "number": 10308
    }
  },
  "person": {
    "salutation": "Frau",
    "firstName": "Inge",
    "lastName": "Musterfrau"
  },
  "note": "Notizen",
  "archived": false
}

GET {resourceurl}/v1/contacts/{id}

Returns the contact with id value {id}.

Update a Contact

PUT {resourceurl}/v1/contacts/{id}

Update an existing contact with id {id} with the data given in the payload as JSON. Returns an action result on success.

For information about required fields please see Create a contact.

Filtering Contacts

GET {resourceurl}/v1/contacts?filter_1=value_1&...&filter_n=value_n

Sample request for retrieveng all contacts

curl https://api.lexoffice.io/v1/contacts/?page=0
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "content": [
  {
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "version": 0,
    "roles": {
      "customer": {
        "number": 10308
      }
    },
    "person": {
      "salutation": "Frau",
      "firstName": "Inge",
      "lastName": "Musterfrau"
    },
    "archived": false
  },
  {
    "id": "313ef116-a432-4823-9dfe-1b1200eb458a",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "version": 0,
    "roles": {
      "customer": {
        "number": 10309
      }
    },
    "person": {
      "salutation": "Herr",
      "firstName": "Max",
      "lastName": "Mustermann"
    },
    "archived": true
  }
],
"totalPages": 1,
"totalElements": 2,
"last": true,
"sort": [
  {
    "direction": "ASC",
    "property": "name",
    "ignoreCase": false,
    "nullHandling": "NATIVE",
    "ascending": true
  }
],
"size": 25,
"number": 0,
"first": true,
"numberOfElements": 2
}

Sample request for a filter with email max@gmx.de and name Mustermann:

curl https://api.lexoffice.io/v1/contacts/?email=max@gmx.de&name=Mustermann
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample call Filter only vendor contacts:

curl https://api.lexoffice.io/v1/contacts/?vendor=true&customer=false
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Returns the contacts that fulfill the criteria given by filters filter_1 to filter_n using a paging mechanism. If more than one filter is given, the logical connector is AND. Filters that are not set are ignored.

Note that a filter should not be present more than once in a request.

The following table describes the possible filter parameters.

Parameter Description
email
string
filters contacts where any of their email addresses inside the emailAddresses JSON object match the given email value. At least 3 characters are necessary to successfully complete the query.
name
string
filters contacts whose name matches the given name value. At least 3 characters are necessary to successfully complete the query.
number
integer
returns the contacts with the specified contact number. Number is either the customer number or the vendor number located in the roles object.
customer
boolean
if set to true filters contacts that have the role customer. If set to false filters contacts that do not have the customer role.
vendor
boolean
if set to true filters contacts that have the role vendor. If set to false filters contacts that do not have the vendor role.

Countries Endpoint

Purpose

The countries endpoint provides read access to the list of countries known to lexoffice.

Country properties

                    Property Description
countryCode
string
The country's code. See our FAQ for specification.
countryNameEN
string
Country name (English)
countryNameDE
string
Country name (German translation)
taxClassification
enum
Tax classification. Possible values are de (Germany), intraCommunity (eligible for Innergemeinschaftliche Lieferung), and thirdPartyCountry (other). See below

Country tax classification

The tax classification as supplied by the countries endpoint refers to the current classification of the country. As countries enter or leave the EU, their classification may be subject to change. At this time, the countries endpoint will always return the current state.

When a country bearing the intraCommunity classification is referred to in vouchers, their tax type may be eligible to be set to intraCommunitySupply. However, that decision may be based on other properties of the organization and the referenced contact information.

Retrieve List of Countries

Sample Request

curl https://api.lexoffice.io/v1/countries
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

[
    {
        "countryCode": "DE",
        "countryNameDE": "Deutschland",
        "countryNameEN": "Germany",
        "taxClassification": "de"
    },
    {
        "countryCode": "FR",
        "countryNameDE": "Frankreich",
        "countryNameEN": "France",
        "taxClassification": "intraCommunity"
    },
    {
        "countryCode": "US",
        "countryNameDE": "Vereinigte Staaten von Amerika",
        "countryNameEN": "United States",
        "taxClassification": "thirdPartyCountry"
    }
]

GET {resourceurl}/v1/countries

The following sample shows how to retrieve list of currently known countries. It is required to replace the placeholder {accessToken} before sending the request.

Credit Notes Endpoint

Purpose

This endpoint provides read and write access to credit notes and also the possibility to render the document as a PDF in order to download it. Credit notes can be created as a draft or finalized in open mode.

With a credit note the partial or full amount of an invoice can be refunded to a customer.

At the moment, credit notes can only be created without any reference to an invoice. To refer a credit note to an invoice on the printed document, the invoice number can be included in the header text (introduction).

It is possible to create credit notes with value-added tax such as of type net (Netto), gross (Brutto) or different types of vat-free. For tax-exempt organizations vat-free (Steuerfrei) credit notes can be created exclusively. All other vat-free tax types are only usable in combination with a referenced contact in lexoffice. For recipients within the EU these are intra-community supply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructional services (Bauleistungen gem. §13b UStG) and external services (Fremdleistungen innerhalb der EU gem. §13b UStG). For credit notes to third countries, the tax types third party country service (Dienstleistungen an Drittländer) and third party country delivery (Ausfuhrlieferungen an Drittländer) are possible.

Credit Notes Properties

Sample of a credit note with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "createdDate": "2019-06-17T18:32:07.480+02:00",
    "updatedDate": "2019-06-17T18:32:07.551+02:00",
    "version": 1,
    "language": "de",
    "archived": false,
    "voucherStatus": "draft",
    "voucherNumber": "GS0007",
    "voucherDate": "2017-02-22T00:00:00.000+01:00",
    "address": {
        "name": "Bike & Ride GmbH & Co. KG",
        "supplement": "Gebäude 10",
        "street": "Musterstraße 42",
        "city": "Freiburg",
        "zip": "79112",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Abus Kabelschloss Primo 590 ",
            "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
            "quantity": 2,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 13.4,
                "grossAmount": 15.946,
                "taxRatePercentage": 19
            },
            "lineItemAmount": 26.8
        },
        {
            "type": "custom",
            "name": "Energieriegel Testpaket",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 5,
                "grossAmount": 5,
                "taxRatePercentage": 0
            },
            "lineItemAmount": 5
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 31.8,
        "totalGrossAmount": 36.89,
        "totalTaxAmount": 5.09
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 0,
            "taxAmount": 0,
            "netAmount": 5
        },
        {
            "taxRatePercentage": 19,
            "taxAmount": 5.09,
            "netAmount": 26.8
        }
    ],
    "taxConditions": {
        "taxType": "net"
    },
    "title": "Rechnungskorrektur",
    "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
    "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut.",
    "files": {
      "documentFileId": "a79fea19-a892-4ea9-89ad-e879946329a3"
    }
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the credit note belongs to.
Read-only.
createdDate
dateTime
The instant of time when the credit note was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the credit note was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the credit note which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
archived
boolean
Specifies if the credit note is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the credit note. Possible values are draft (is editable), open (finalized and no longer editable but not yet paid off), paidoff (has been fully paid back to the customer), voided (cancelled)
Read-only.
voucherNumber
string
The specific number a credit note is aware of. This consecutive number is set by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of credit note in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
address
object
The address of the credit note recipient. For details see below.
lineItems
list
The items of the credit note. For details see below.
totalPrice
object
The total price of the credit note. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the credit note. For details see below.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send. We recommended to include the invoice number in the header when the credit note is related to an invoice.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
files
object
The document id for the PDF version of the credit note. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of a credit note. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific credit note. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the credit note recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new credit note.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the credit note recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the credit note recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the credit note. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Files Details

                    Property Description
documentFileId
uuid
The id of the credit note PDF. The PDF will be created when the credit note turns from draft into status open or paidoff. To download the credit note PDF file please use the files endpoint.

Create a Credit Note

Sample Request to create a credit note

curl https://api.lexoffice.io/v1/credit-notes
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
  "archived": false,
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "taxRatePercentage": 19
      }
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      }
    },
    {
      "type": "text",
      "name": "Strukturieren Sie Ihre Belege durch Text-Elemente.",
      "description": "Das hilft beim Verständnis"
    }
  ],
  "totalPrice": {
    "currency": "EUR"
   },
  "taxConditions": {
    "taxType": "net"
  },
  "title": "Rechnungskorrektur",
  "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
  "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut."
}
'

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "resourceUri": "https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "createdDate": "2019-06-17T18:32:07.480+02:00",
  "updatedDate": "2019-06-17T18:32:07.551+02:00",
  "version": 1
}

POST {resourceurl}/v1/credit-notes[?finalize=true]

Credit notes transmitted via the API are created in draft mode per default. To create a finalized credit note with status open the optional query parameter finalize has to be set. The status of a credit note cannot be changed via the api.

The created credit note will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers. To provide your customers access to the created credit note please use our deeplink function.

The contents of the credit note are expected in the request's body as an application/json and must not contain read-only fields.

Description of required properties when creating a credit note.

                    Property Required Notes
voucherDate Yes
address Yes Nested object. Required fields for address please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.

Address Required Properties

Description of required address properties when creating a credit note.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating a credit note. At this point only line items of type "custom" and "text" are supported.

                    Property Required Notes
type Yes Supported values are custom and text. Other types of line items may be returned by a GET operation.
name Yes
quantity *
unitName *
unitPrice * Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating a credit note.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes Must be 0 for vat-free sales voucher.

Total Price Required Properties

Description of required totalPrice properties when creating a credit note.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating a credit note.

                    Property Required Notes
taxType Yes Supported values are: gross, net, vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, thirdPartyCountryDelivery.

Retrieve a Credit Note

Sample request

curl https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response


{
    "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "createdDate": "2019-06-17T18:32:07.480+02:00",
    "updatedDate": "2019-06-17T18:32:07.551+02:00",
    "version": 1,
    "language": "de",
    "archived": false,
    "voucherStatus": "draft",
    "voucherNumber": "GS0007",
    "voucherDate": "2017-02-22T00:00:00.000+01:00",
    "address": {
        "name": "Bike & Ride GmbH & Co. KG",
        "supplement": "Gebäude 10",
        "street": "Musterstraße 42",
        "city": "Freiburg",
        "zip": "79112",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Abus Kabelschloss Primo 590 ",
            "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
            "quantity": 2,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 13.4,
                "grossAmount": 15.946,
                "taxRatePercentage": 19
            },
            "lineItemAmount": 26.8
        },
        {
            "type": "custom",
            "name": "Energieriegel Testpaket",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 5,
                "grossAmount": 5,
                "taxRatePercentage": 0
            },
            "lineItemAmount": 5
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 31.8,
        "totalGrossAmount": 36.89,
        "totalTaxAmount": 5.09
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 0,
            "taxAmount": 0,
            "netAmount": 5
        },
        {
            "taxRatePercentage": 19,
            "taxAmount": 5.09,
            "netAmount": 26.8
        }
    ],
    "taxConditions": {
        "taxType": "net"
    },
    "title": "Rechnungskorrektur",
    "introduction": "Rechnungskorrektur zur Rechnung RE-00020",
    "remark": "Folgende Lieferungen/Leistungen schreiben wir Ihnen gut."
}

GET {resourceurl}/v1/credit-notes/{id}

Returns the credit note with id value {id}.

Render a Credit Note Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/credit-notes/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "b26e1d73-19ff-46b1-8929-09d8d73d4167"
}

GET {resourceurl}/v1/credit-notes/{id}/document

To download the pdf file of a credit note document, you need its documentFileId. This id is usually returned by the credit note resource. However, newly created credit notes in status open via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the credit note pdf document via the (Files Endpoint).

Credit notes can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If a credit note is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/credit-notes/view/{id}

Edit URL {appbaseurl}/permalink/credit-notes/edit/{id}

Down Payment Invoices Endpoint

Purpose

This endpoint provides read-only access to down payment invoices.

Down Payment Invoices Properties

Most properties of down payment invoices are identical with the ones of regular invoices.

Sample of a down payment invoice. Fields with no content are displayed with "null" just for demonstration purposes.

{
  "id": "0333f0c7-2b89-4889-b64e-68b3ca3f167a",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2021-01-20T10:26:40.956+01:00",
  "updatedDate": "2021-01-21T13:34:13.228+01:00",
  "version": 3,
  "language": "de",
  "archived": false,
  "voucherStatus": "open",
  "voucherNumber": "RE1129",
  "voucherDate": "2021-01-20T10:26:26.565+01:00",
  "dueDate": "2021-02-19T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Pauschaler Abschlag",
      "quantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 559.66,
        "grossAmount": 666,
        "taxRatePercentage": 19
      },
      "lineItemAmount": 666.00
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 559.66,
    "totalGrossAmount": 666.00,
    "totalTaxAmount": 106.34
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 19,
      "taxAmount": 106.34,
      "netAmount": 559.66
    }
  ],
  "taxConditions": {
    "taxType": "gross"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingType": "none"
  },
  "closingInvoiceId": null,
  "introduction": "Wie vereinbart, erlauben wir uns folgenden pauschalen Abschlag in Rechnung zu stellen.",
  "remark": "Vielen Dank für die gute Zusammenarbeit.",
  "files": {
    "documentFileId": "aa0388c5-20b5-49d7-96ce-0c08ac0482f4"
  },
  "title": "1. Abschlagsrechnung"
}

All attributes are read-only, as down payment invoices cannot be created or modified by means of the API.

                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
organizationId
uuid
Unique id of the organization the down payment invoice belongs to.
createdDate
dateTime
The instant of time when the down payment invoice was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the down payment invoice was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the down payment invoice which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
archived
boolean
Specifies if the down payment invoice is only available in the archive in lexoffice.
voucherStatus
enum
Specifies the status of the down payment invoice. Possible values are draft (is editable), open (finalized and no longer editable but yet unpaid or only partially paid), paid (has been fully paid), voided (cancelled)
voucherNumber
string
The specific number a down payment invoice is aware of. This consecutive number is set by lexoffice on creation.
voucherDate
dateTime
The date of the down payment invoice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
dueDate
dateTime
Sets the date on which the down payment invoice is payable before becoming overdue in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
address
object
The address of the down payment invoice recipient. For details see below.
lineItems
list
The items of the down payment invoice. For down payment invoices, this list contains exactly one item. For details see below.
totalPrice
object
The total price of the down payment invoice. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
taxConditions
object
The tax conditions of the down payment invoice. For details see below.
paymentConditions
object
The payment conditions of the down payment invoice. The organization's (or contact-specific) default is used if no value was send. For details see below.
shippingConditions
object
The shipping conditions of the invoice. For details see below.
closingInvoiceId
UUID
Id of the closing invoice that references this down payment invoice, if one exists. Null otherwise.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
files
object
The document id for the PDF version of the down payment invoice. For details see below.

Address Details

There are two main options to address the recipient of a down payment invoice. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific down payment invoice. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the down payment invoice recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new down payment invoice.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the down payment invoice recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the down payment invoice recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the down payment invoice. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Payment Conditions Details

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.

Files Details

                    Property Description
documentFileId
uuid
The id of the down payment invoice PDF. The PDF will be created when the invoice turns from draft into status open. To download the invoice PDF file please use the files endpoint.



Retrieve a Down Payment Invoice

Sample request

curl https://api.lexoffice.io/v1/down-payment-invoices/28af0062-5b19-11eb-9609-57d780e21aed
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"

Sample response

{
  "id": "0333f0c7-2b89-4889-b64e-68b3ca3f167a",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2021-01-20T10:26:40.956+01:00",
  "updatedDate": "2021-01-21T13:34:13.228+01:00",
  "version": 3,
  "language": "de",
  "archived": false,
  "voucherStatus": "open",
  "voucherNumber": "RE1129",
  "voucherDate": "2021-01-20T10:26:26.565+01:00",
  "dueDate": "2021-02-19T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Pauschaler Abschlag",
      "quantity": 1,
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 559.66,
        "grossAmount": 666,
        "taxRatePercentage": 19
      },
      "lineItemAmount": 666.00
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 559.66,
    "totalGrossAmount": 666.00,
    "totalTaxAmount": 106.34
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 19,
      "taxAmount": 106.34,
      "netAmount": 559.66
    }
  ],
  "taxConditions": {
    "taxType": "gross"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingType": "none"
  },
  "closingInvoiceId": "4ba90e2d-c206-4bb0-a135-3e714db617fb",
  "introduction": "Wie vereinbart, erlauben wir uns folgenden pauschalen Abschlag in Rechnung zu stellen.",
  "remark": "Vielen Dank für die gute Zusammenarbeit.",
  "files": {
    "documentFileId": "aa0388c5-20b5-49d7-96ce-0c08ac0482f4"
  },
  "title": "1. Abschlagsrechnung"
}

GET {resourceurl}/v1/down-payment-invoices/{id}

Returns the down payment invoice with id value {id}.

Down payment invoices can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If a down payment invoice is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/invoices/view/{id}

Edit URL {appbaseurl}/permalink/invoices/edit/{id}

Event Subscriptions Endpoint

Purpose

Using event subscriptions you will be notified about certain events on resources - e.g. you receive a notification every time a contact changes in lexoffice. This will make pull requests superfluous to keep your data synced between lexoffice and your application. The notifications are implemented as webhooks. Subscribing to an event simply requires the event type and your callback url. With the event-subscriptions endpoint you can manage your subscriptions within lexoffice.

Event Subscriptions Properties

Sample of an created event subscription.

{
  "subscriptionId": "4d43ad14-671d-4e0c-fd4b-2fd8cc117eff",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2018-04-11T12:15:00.000+02:00",
  "eventType": "contact.changed",
  "callbackUrl": "https://example.org/webhook"
}
                    Property Description
subscriptionId
uuid
Unique id of the event subscription generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the event subscription belongs to.
Read-only.
createdDate
dateTime
The instant of time when the event subscription was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
eventType
string
The event type is a combined key which defines the resource and its event name you are subscribing to. All available events receivable via the API can be taken from the table Event Types.
callbackUrl
string
When a resource entity triggers an event, the callback url is used to notify the subscriber about it. The payload of the callback is described in Webhook Callback Properties.

Event Types

The following table lists all types of events you can subscribe to. The property EventType is the combined key of a resource and a event name. The EventType is handled in lower case.

Resource Event type Description
contacts contact.created A new contact was created in lexoffice.
contacts contact.changed A lexoffice contact has changed. You should get the updated contact details.
contacts contact.deleted A lexoffice contact was deleted. Depending on your application, you should unlink the lexoffice contact on your site or delete it as well.
credit-notes credit-note.created A new credit note was created in lexoffice. Get the new credit note by calling the credit notes endpoint.
credit-notes credit-note.changed A credit note has changed. Get the updated credit note by calling the credit notes endpoint. Please note that the status may also have changed.
credit-notes credit-note.deleted A credit note was deleted in lexoffice.
credit-notes credit-note.status.changed The status of a credit note has changed. Update the credit note by calling the credit notes endpoint to retrieve the new status.
invoices invoice.created A new invoice was created in lexoffice. Get the new invoice by calling the invoices endpoint.
invoices invoice.changed An invoice has changed. Get the updated invoice by calling the invoices endpoint. Please note that the status may also have changed.
invoices invoice.deleted An invoice was deleted in lexoffice.
invoices invoice.status.changed The status of an invoice has changed. Update the invoice by calling the invoices endpoint to retrieve the new status.
down-payment-invoices down-payment-invoice.created A new down payment invoice was created in lexoffice. Get the new down payment invoice by calling the down payment invoices endpoint.
down-payment-invoices down-payment-invoice.changed A down payment invoice has changed. Get the updated down payment invoice by calling the down payment invoices endpoint. Please note that the status may also have changed.
down-payment-invoices down-payment-invoice.deleted A down payment invoice was deleted in lexoffice.
down-payment-invoices down-payment-invoice.status.changed The status of a down payment invoice has changed. Update the down payment invoice by calling the down payment invoices endpoint to retrieve the new status.
order-confirmations order-confirmation.created A new order confirmation was created in lexoffice. Get the new order confirmation by calling the order confirmations endpoint.
order-confirmations order-confirmation.changed An order confirmation has changed. Get the updated order confirmation by calling the order confirmations endpoint. Please note that the status may also have changed.
order-confirmations order-confirmation.deleted An order confirmation was deleted in lexoffice.
order-confirmations order-confirmation.status.changed The status of an order confirmation has changed. Update the order confirmation by calling the order confirmations endpoint to retrieve the new status. Please note that at this time there are no status transitions triggering the status changed event for order confirmations. This event solely exists to provide symmetric events for all voucher types.
quotations quotation.created A new quotation was created in lexoffice. Get the new quotation by calling the quotations endpoint.
quotations quotation.changed A quotation has changed. Get the updated quotation by calling the quotations endpoint. Please note that the status may also have changed.
quotations quotation.deleted A quotation was deleted in lexoffice.
quotations quotation.status.changed The status of a quotation has changed. Update the quotation by calling the quotations endpoint to retrieve the new status.
revoke token.revoked The refresh token was revoked, hence is invalid. The resourceId in the webhook callback refers to the connectionId you retrieve using the profile endpoint. Please store the refresh token to the connectionId prior to the registration on this event.
vouchers voucher.created A new (bookkeeping) voucher was created in lexoffice. Get the new voucher by calling the vouchers endpoint.
vouchers voucher.changed A voucher has changed. Get the updated voucher by calling the vouchers endpoint.
vouchers voucher.deleted A voucher was deleted in lexoffice.
vouchers voucher.status.changed The status of a voucher has changed. Get the updated voucher by calling the vouchers endpoint.
credit-notes, invoices, vouchers payment.changed The payment of a bookkeeping or sales voucher has changed due to a manual payment or a transaction assignment. Please use the payments endpoint or the respective resource endpoints to retrieve further informaton about the payment status of the resource
recurring-templates recurring-template.created A new template for recurring invoices was created in lexoffice. Get the new recurring template by calling the recurring templates endpoint.
recurring-templates recurring-template.changed A template for recurring invoices has changed. Get the updated recurring template by calling the recurring templates endpoint.
recurring-templates recurring-template.deleted A template for recurring invoices was deleted in lexoffice.

Webhook Callback Properties

Sample payload from a webhook callback of an event subscription.

{
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "eventType": "contact.changed",
  "resourceId": "4d43ad14-671d-4e0c-fd4b-2fd8cc117eff",
  "eventDate": "2018-04-11T12:30:00.000+02:00"
}

Subscribed events will send a POST request to your given webhook url and contain the following JSON payload.

                    Property Description
organizationId
uuid
The organization for which an event has been triggered.
eventType
string
Describes the occurred event. The eventType describes the resource and the event name.
resourceId
uuid
The resource entity on which the event has occurred. Use the corresponding resource endpoint and the resourceId to get the latest data of the resource entity.
eventDate
dateTime
The instant of time when the event was triggered in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.

Verify Authenticity

For verification that the webhook call was sent from lexoffice, every webhook contains an RSA-SHA512 encrypted signature of the JSON request body (without whitespaces and linebreaks) in a base64 encoded header called X-Lxo-Signature. To verify it, please use this public key.

Example signature verification with OpenSSL

Sample Signature Verification with OpenSSL

openssl dgst -sha512 -verify public_key.pub -signature sample_signature_decoded sample_payload.json

The signature can be verified using openssl. With the public key, a sample payload and the decoded signature, openssl can be used to verify the signature. It should print Verified OK.

Sample decoding of base64 encoded signature

openssl base64 -d -in sample_signature_base64 -out  signature_decoded

The signature from the X-Lxo-Signature header is base64 encoded and needs to be decoded before calling the former command. For this example, this is the sample base64 encoded signature.

Create an Event Subscription

Sample Request to create an event subscription

curl https://api.lexoffice.io/v1/event-subscriptions
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
    "eventType": "contact.changed",
    "callbackUrl": "https://example.org/webhook"
}'

Sample response

{
    "id": "49aa2f76-c51a-4df3-ae83-3a103d781494",
    "resourceUri": "https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494",
    "createdDate": "2018-04-11T12:20:00.000+02:00",
    "updatedDate": "2018-04-11T12:20:00.000+02:00",
    "version": 0
}

POST {resourceurl}/v1/event-subscriptions

To subscribe to an event, provide the event type and the webhook callback url in the request body. The endpoint returns an action result (HTTP status code 201 Created) on success.

                    Property Required Notes
eventType Yes The name of the event usually a combined key containing the resource and the event name.
callbackUrl Yes Your webhook HTTPS url where you will be notified on events. A HEAD request will be sent to the given URL to determine if SSL certificates are correct. If this fails the endpoint returns a 406 HTTP status code.

Retrieve an Event Subscription

Sample request to retrieve all event subscriptions

curl https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
    "subscriptionId": "49aa2f76-c51a-4df3-ae83-3a103d781494",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "createdDate": "2018-04-11T12:20:00.000+02:00",
    "eventType": "contact.changed",
    "callbackUrl": "https://example.org/webhook"
}

GET {resourceurl}/v1/event-subscriptions/{subscriptionId}

Returns the event subscription with the id {subscriptionId}.

Retrieve all Event Subscriptions

Sample Request to retrieve all event subscriptions

curl https://api.lexoffice.io/v1/event-subscriptions
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
    "content": [
        {
            "subscriptionId": "49aa2f76-c51a-4df3-ae83-3a103d781494",
            "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
            "createdDate": "2018-04-11T12:20:00.000+02:00",
            "eventType": "contact.changed",
            "callbackUrl": "https://example.org/webhook"
        }
    ]
}

GET {resourceurl}/v1/event-subscriptions

Returns all your event subscriptions.

Delete an Event Subscription

Sample Request to delete an event subscription

curl https://api.lexoffice.io/v1/event-subscriptions/49aa2f76-c51a-4df3-ae83-3a103d781494
-X DELETE
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

DELETE {resourceurl}/v1/event-subscriptions/{subscriptionId}

Deletes an event subscription with the id {subscriptionId}. On success, you will receive a status code 204 (No Content).

Files Endpoint

Purpose

Use this endpoint to upload and/or download files, e.g. vouchers or invoices.

Upload a file

POST {resourceurl}/v1/files

Sample Request file upload

curl https://api.lexoffice.io/v1/files
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: multipart/form-data"
-H "Accept: application/json"
-F "file=@{PathToFile}" -F "type=voucher"

Uploading files to lexoffice are HTTP multipart requests where the Content-Type header must be set to multipart/form-data and the file contents have to be sent as binary data. Moreover, it is required to specify the upload type which must be included to the form data with name = type and e.g. value = voucher.

Available upload types and its valid file formats are:

upload type file formats max file size Description
voucher pdf, jpg, png 5 MB Upload voucher images for bookkeeping purposes.

Sample Response

{
  "id": "8118c402-1c70-4da1-a9f1-a22f480cc623"
}

A successful upload returns a HTTP status 202 Accepted along with the file id.

Upload requests containing invalid file contents or causing errors during image processing are responded with HTTP status 406 Not Acceptable. The returned response body should give reasons about the rejection.

If the upload type is not provided or is not valid, a HTTP status 400 Bad Request will be returned. If no file is provided, the file upload endpoint returns HTTP status 500.

Download a file

GET {resourceurl}/v1/files/{id}[?renderType={value}]

Sample request file download

curl "https://api.lexoffice.io/v1/files/{id}"
-X GET
-H "Accept: */*"
-H "Authorization: Bearer {accessToken}"

Returns the file as binary data with id value {id}. The HTTP header fields Content-Type specifies the file type (MIME type) and the Content-Length the size of the file in bytes. A suggested file name is returned in the header Content-Disposition.

Optional Download Parameters

For some file resources different download options are possible via query string parameter.

                 Parameter Name Description
renderType
string
Render Type Only usable if the file is related to an invoice resource.
Enables to download the invoice pdf files with other predefined printing options. Possible values are: factoring (without letter paper and bank details).

XRechnung and the Accept header

The files endpoint provides an abstract method to download various types of files associated with both sales and bookkeeping vouchers. Historically, the Accept header was ignored, and the file was returned, regardless of its actual and the requested media types.

By sending different Accept headers, the client can choose between multiple representation files of a voucher, especially for XRechnung. With the XRechnung support in lexoffice, the files endpoint may return different files for different Accept headers.

Simply put: Send Accept: */* for all regular purposes; use Accept: application/xml to retrieve the XRechnung XML file.

Newly uploaded and unassigned files for bookkeeping in lexoffice can be accessed via the following deeplink for further processing by the user, e.g. creating a voucher.

View URL {appbaseurl}/permalink/files/view

Invoices Endpoint

Purpose

This endpoint provides read and write access to invoices. The created document(s) can be rendered as PDF files, and, depending on the input data, in the German XRechung data format. PDF files can be downloaded. Invoices can be created in draft or open (finalized) states.

A higher level description of the handling of invoices via the lexoffice API can be found in the invoice cookbook (German only).

It is possible to create invoices with value-added tax such as of type net (Netto), gross (Brutto) or different types of vat-free. For tax-exempt organizations vat-free (Steuerfrei) invoices can be created exclusively. All other vat-free tax types are only usable in combination with a referenced contact in lexoffice. For recipients within the EU these are intra-community supply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructional services (Bauleistungen gem. §13b UStG) and external services (Fremdleistungen innerhalb der EU gem. §13b UStG). For invoices to third countries, the tax types third party country service (Dienstleistungen an Drittländer) and third party country delivery (Ausfuhrlieferungen an Drittländer) are possible.

Read-only support for invoices for down payment (Abschlagsrechnung) is provided by the Down Payment Invoice Endpoint.

Invoices Properties

Sample of an invoice with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "language": "de",
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "RE1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "dueDate": null,
  "address": {
    "contactId": null,
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "xRechnung": null,
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "id": null,
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "description": null,
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    },
    {
      "type": "text",
      "name": "Freitextposition",
      "description": "This item type can contain either a name or a description or both."
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13,
    "totalDiscountAbsolute": null,
    "totalDiscountPercentage": null
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net",
    "taxTypeNote": null
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingEndDate": null,
    "shippingType": "delivery"
  },
  "closingInvoice": false,
  "claimedGrossAmount": null,
  "downPaymentDeductions": null,
  "recurringTemplateId": null,
  "title": "Rechnung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "files": {
    "documentFileId": "75295db7-7e69-4630-befd-a7f4ddfdaa83"
  }
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the invoice belongs to.
Read-only.
createdDate
dateTime
The instant of time when the invoice was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the invoice was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the invoice which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
archived
boolean
Specifies if the invoice is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the invoice. Possible values are draft (is editable), open (finalized and no longer editable but yet unpaid or only partially paid), paid (has been fully paid), voided (cancelled)
Read-only.
voucherNumber
string
The specific number an invoice is aware of. This consecutive number is set by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of the invoice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
dueDate
dateTime
Sets the date on which the invoice is payable before becoming overdue in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
address
object
The address of the invoice recipient. For details see below.
xRechnung
object
XRechnung related properties for XRechnung enabled invoices. For details see below
lineItems
list
The items of the invoice. For details see below.
totalPrice
object
The total price of the invoice. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the invoice. For details see below.
paymentConditions
object
The payment conditions of the invoice. The organization's (or contact-specific) default is used if no value was send. For details see below.
shippingConditions
object
The shipping conditions of the invoice. For details see below.
closingInvoice
boolean
Denotes whether this invoice is a closing invoice (Schlussrechnung)
Read-only.
claimedGrossAmount
number
The remaining gross amount (see description below)
Read-only.
downPaymentDeductions
list
The down payments connected to this closing invoice.
Read-only.
recurringTemplateId
UUID
The id of the recurring template, if this is a recurring invoice deduced from a template. Null otherwise.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
files
object
The document id for the PDF version of the invoice. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of an invoice. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific invoice. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the invoice recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new invoice.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the invoice recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the invoice recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the invoice. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Payment Conditions Details

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the invoice.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Shipping Conditions Details

                    Property Description
shippingDate
dateTime
The instant of time when the purchased items have to be shipped. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
shippingEndDate
dateTime
An end instant in order to specify a shipping period of time. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00). Must not specify an instant before shippingDate.
shippingType
enum
The type of the shipping. Possible values are service (a service is supplied on shippingDate), serviceperiod (a service is supplied within the period [shippingDate,shippingEndDate] ), delivery (a product is delivered), deliveryperiod (a product is delivered within the period [shippingDate,shippingEndDate]) and none (no shipping date has to be provided)

Down Payment Deductions Details

Use the Down Payment Invoices endpoint to retrieve details of a down payment invoice.

 Property Description
id
uuid
The down payment deduction's unique id.
voucherType
string
Voucher type of the down payment. Currently, always contains the string downpaymentinvoice.
title
string
Down payment's title
voucherNumber
string
Down payment's voucher number
voucherDate Down payment's date in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
receivedGrossAmount
number
The gross amount received for this down payment invoice
receivedNetAmount
number
The net amount received for this down payment invoice
receivedTaxAmount
number
Tax received for this down payment invoice
taxRatePercentage
number
The tax rate used for amount calculation in this down payment invoice

As closing invoices are currently read-only, all of the attributes listed above are read-only.

Files Details

                    Property Description
documentFileId
uuid
The id of the invoice PDF. The PDF will be created when the invoice turns from draft into status open. To download the invoice PDF file please use the files endpoint.



XRechnung Details

XRechnung properties are only relevant if an XRechnung enabled contact is referenced. In this case, if xRechnung is ommitted, the contact's buyer reference is used by default. If xRechnung is present, buyerReference is a mandatory field.

The buyerReference (Leitweg-ID) stored in the referenced contact can be overwritten for a specific invoice by transmitting a different buyerReference during invoice creation. If a buyer reference is specified, but the linked contact has no buyer reference and vendor number at the customer, request attempts are rejected with 406.

It is also possible to create a standard invoice for an XRechnung enabled contact. To do so, please set the buyerReference to an empty string.

                    Property Description
buyerReference
string
The customer's Leitweg-ID for XRechnung enabled invoices

Closing invoices

lexoffice provides closing invoices (Schlussrechnungen), representing the last invoice for a project, and referencing a number of down payments (Abschlagsrechnungen). Closing invoices have a number of unique properties:

At the moment, the API only provides read only access to closing invoices; the three attributes are read-only.

Create an Invoice

Sample Request to create an invoice

curl https://api.lexoffice.io/v1/invoices
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
 "archived": false,
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
   "address": {
   "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0
    },
    {
      "type": "text",
      "name": "Strukturieren Sie Ihre Belege durch Text-Elemente.",
      "description": "Das hilft beim Verständnis"
    }
  ],
  "totalPrice": {
    "currency": "EUR"
   },
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "title": "Rechnung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf"
}
'

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "resourceUri": "https://api.lexoffice.io/v1/invoices/66196c43-bfee-baf3-4335-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/invoices[?finalize=true]

Invoices transmitted via the API are created in draft mode per default. To create a finalized invoice with status open the optional query parameter finalize has to be set. The status of an invoice cannot be changed via the api.

The created invoice will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers. To provide your end-users access to the created invoice please use our deeplink function.

It is possible to create invoices in the XRechnung data format by referencing a contact which is entitled to receive an XRechnung. Please note that an extended validation conforming to the XRechnung specification will be performed when creating such an invoice. More information can be found in the XRechnung FAQ.

The contents of the invoice are expected in the request's body as an application/json and must not contain read-only fields.

Description of required properties when creating an invoice.

                    Property Required Notes
voucherDate Yes
address Yes Nested object. Required fields for address please see below.
xRechnung * Nested object. The given buyer reference id of the xRechnung object overwrites the buyer reference specified in the linked contact, only for this invoice. Details of nested object please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.
shippingConditions Yes Nested object. Required fields for shippingConditions please see below.

XRechnung Required Properties

Description of required xRechnung properties when creating an invoice.

XRechnung properties are only relevant if an XRechnung enabled contact is referenced. In this case, if xRechnung is ommitted, the contact's buyer reference is used by default. If xRechnung is present, buyerReference is a mandatory field.

The buyerReference (Leitweg-ID) stored in the referenced contact can be overwritten for a specific invoice by transmitting a different buyerReference during invoice creation. If a buyer reference is specified, but the linked contact has no buyer reference and vendor number at the customer, request attempts are rejected with 406.

It is also possible to create a standard invoice for an XRechnung enabled contact. To do so, please set the buyerReference to an empty string.

                    Property Required Notes
buyerReference * Only when overwriting the buyer reference for the referenced contact only for this invoice or to create a standard invoice by setting it to an empty string.

Address Required Properties

Description of required address properties when creating an invoice.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating an invoice. At this point only line items of type "custom" and "text" are supported.

                    Property Required Notes
type Yes Supported values are custom and text. Other types of line items may be returned by a GET operation.
name Yes
quantity *
unitName *
unitPrice * Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating an invoice.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes Must be 0 for vat-free sales voucher.

Total Price Required Properties

Description of required totalPrice properties when creating an invoice.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating an invoice.

                    Property Required Notes
taxType Yes Supported values are: gross, net, vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, thirdPartyCountryDelivery.

Shipping Condition Required Properties

Description of required shipping condition properties when creating an invoice.

                    Property Required Notes
shippingType Yes
shippingDate * Required for shipping types service, serviceperiod, delivery and deliveryperiod.
shippingEndDate * Required for shipping types serviceperiod and deliveryperiod.

Retrieve an Invoice

Sample request

curl https://api.lexoffice.io/v1/invoices/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"

Sample response


{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "language": "de",
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "RE1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "title": "Rechnung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf"
}

GET {resourceurl}/v1/invoices/{id}

Returns the invoice with id value {id}.

Render an Invoice Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/invoices/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "b26e1d73-19ff-46b1-8929-09d8d73d4167"
}

GET {resourceurl}/v1/invoices/{id}/document

To download the pdf file of an invoice document, you need its documentFileId. This id is usually returned by the invoice resource. However, newly created invoices in status open via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the invoice pdf document via the Files Endpoint.

Invoices can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If an invoice is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/invoices/view/{id}

Edit URL {appbaseurl}/permalink/invoices/edit/{id}

Order Confirmations Endpoint

Purpose

This endpoint provides read and write access to order confirmations and also the possibility to render the document as a PDF in order to download it. Order confirmations are always created in draft mode and do not need to be finalized.

It is possible to create order confirmations with value-added tax such as of type net (Netto), gross (Brutto) or different types of vat-free. For tax-exempt organizations vat-free (Steuerfrei) order confirmations can be created exclusively. All other vat-free tax types are only usable in combination with a referenced contact in lexoffice. For recipients within the EU these are intra-community supply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructional services (Bauleistungen gem. §13b UStG) and external services (Fremdleistungen innerhalb der EU gem. §13b UStG). For order confirmations to third countries, the tax types third party country service (Dienstleistungen an Drittländer) and third party country delivery (Ausfuhrlieferungen an Drittländer) are possible.

Order Confirmations Properties

Sample of an order confirmation with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "language": "de",
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "AB1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "contactId": null,
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "id": null,
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "description": null,
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    },
    {
      "type": "text",
      "name": "Freitextposition",
      "description": "This item type can contain either a name or a description or both."
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13,
    "totalDiscountAbsolute": null,
    "totalDiscountPercentage": null
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net",
    "taxTypeNote": null
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingEndDate": null,
    "shippingType": "delivery"
  },
  "title": "Auftragsbestätigung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "deliveryTerms": "Lieferung an die angegebene Lieferadresse"
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the order confirmation belongs to.
Read-only.
createdDate
dateTime
The instant of time when the order confirmation was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the order confirmation was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the order confirmation which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
archived
boolean
Specifies if the order confirmation is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the order confirmation. The only possible status is draft (is editable).
Read-only.
voucherNumber
string
The specific number an order confirmation is aware of. This consecutive number set is by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of order confirmation in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
address
object
The address of the order confirmation recipient. For details see below.
lineItems
list
The items of the order confirmation. For details see below.
totalPrice
object
The total price of the order confirmation. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the order confirmation. For details see below.
paymentConditions
object
The payment conditions of the order confirmation. The organization's (or contact-specific) default is used if no value was send. For details see below.
shippingConditions
object
The shipping conditions of the order confirmation. For details see below.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
deliveryTerms
string
(Optional) Describes the terms for delivery. The organization's (or contact-specific) default is used if no value was send.
files
object
The document id for the PDF version of the order confirmation. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of an order confirmation. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific order confirmation. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the order confirmation recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new order confirmation.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the order confirmation recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the order confirmation recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the order confirmation. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Payment Conditions Details

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the order confirmation.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Shipping Conditions Details

                    Property Description
shippingDate
dateTime
The instant of time when the purchased items have to be shipped. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
shippingEndDate
dateTime
An end instant in order to specify a shipping period of time. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00). Must not specify an instant before shippingDate.
shippingType
enum
The type of the shipping. Possible values are service (a service is supplied on shippingDate), serviceperiod (a service is supplied within the period [shippingDate,shippingEndDate] ), delivery (a product is delivered), deliveryperiod (a product is delivered within the period [shippingDate,shippingEndDate]) and none (no shipping date has to be provided)

Files Details

                    Property Description
documentFileId
uuid
The id of the order confirmation PDF. To download the order confirmation PDF file please use the files endpoint.

Create an Order Confirmation

Sample Request to create an order confirmation

curl https://api.lexoffice.io/v1/order-confirmations
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
 "archived": false,
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
   "address": {
   "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "type": "custom",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50
    },
    {
      "type": "custom",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0
    },
    {
      "type": "text",
      "name": "Strukturieren Sie Ihre Belege durch Text-Elemente.",
      "description": "Das hilft beim Verständnis"
    }
  ],
  "totalPrice": {
    "currency": "EUR"
   },
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "title": "Auftragsbestätigung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "deliveryTerms": "Lieferung an die angegebene Lieferadresse"
}
'

Sample response

{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "resourceUri": "https://api.lexoffice.io/v1/order-confirmations/66196c43-bfee-baf3-4335-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/order-confirmations

The contents of the order confirmation are expected in the request's body as an application/json and must not contain read-only fields.

The created order confirmation will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers.

To provide your end-users access to the created order confirmation please use our deeplink function.

Description of required properties when creating an order confirmation.

                    Property Required Notes
voucherDate Yes
address Yes Nested object. Required fields for address please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.
shippingConditions Yes Nested object. Required fields for shippingConditions please see below.

Address Required Properties

Description of required address properties when creating an order confirmation.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating an order confirmation. At this point only line items of type "custom" and "text" are supported.

                    Property Required Notes
type Yes Supported values are custom and text. Other types of line items may be returned by a GET operation.
name Yes
quantity *
unitName *
unitPrice * Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating an order confirmation.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes Must be 0 for vat-free sales voucher.

Total Price Required Properties

Description of required totalPrice properties when creating an order confirmation.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating an order confirmation.

                    Property Required Notes
taxType Yes Supported values are: gross, net, vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, thirdPartyCountryDelivery.

Shipping Condition Required Properties

Description of required shipping condition properties when creating an order confirmation.

                    Property Required Notes
shippingType Yes
shippingDate * Required for shipping types service, serviceperiod, delivery and deliveryperiod.
shippingEndDate * Required for shipping types serviceperiod and deliveryperiod.

Retrieve an Order Confirmation

Sample request

curl https://api.lexoffice.io/v1/order-confirmations/e9066f04-8cc7-4616-93f8-ac9ecc8479c8
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response


{
  "id": "e9066f04-8cc7-4616-93f8-ac9ecc8479c8",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2017-04-24T08:20:22.528+02:00",
  "updatedDate": "2017-04-24T08:20:22.528+02:00",
  "version": 0,
  "language": "de",
  "archived": false,
  "voucherStatus": "draft",
  "voucherNumber": "AB1019",
  "voucherDate": "2017-02-22T00:00:00.000+01:00",
  "address": {
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net"
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "shippingConditions": {
    "shippingDate": "2017-04-22T00:00:00.000+02:00",
    "shippingType": "delivery"
  },
  "title": "Auftragsbestätigung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "deliveryTerms": "Lieferung an die angegebene Lieferadresse",
  "files": {
    "documentFileId": "023d5ef7-ad57-46d7-8579-9ffbdf218faf"
  }
}

GET {resourceurl}/v1/order-confirmations/{id}

Returns the order confirmation with id value {id}.

Render an Order Confirmation Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/order-confirmations/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "023d5ef7-ad57-46d7-8579-9ffbdf218faf"
}

GET {resourceurl}/v1/order-confirmations/{id}/document

To download the pdf file of an order confirmation document, you need its documentFileId. This id is usually returned by the order confirmation resource. However, newly created order confirmations via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the order confirmation pdf document via the Files Endpoint.

Order confirmations can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If an order confirmation is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/order-confirmations/view/{id}

Edit URL {appbaseurl}/permalink/order-confirmations/edit/{id}

Payments Endpoint

Purpose

The payments endpoint provides read access to the payment status of (bookkeeping or sales) vouchers, including invoices and credit notes.

Payments properties

Samples of a payment for different voucher types

{
  "openAmount": 200.00,
  "currency": "EUR",
  "paymentStatus": "openRevenue",
  "voucherType": "invoice",
  "voucherStatus": "open"
}


{
  "openAmount": 39.90,
  "paymentStatus": "openExpense",
  "currency": "EUR",
  "voucherType": "purchaseinvoice",
  "voucherStatus": "open"
}

{
  "openAmount": 0,
  "currency": "EUR",
  "paymentStatus": "balanced",
  "voucherType": "purchasecreditnote",
  "voucherStatus": "paidoff"
}
 Property Description
openAmount
number
Open amount. Positive value both for revenues and expenses
currency
enum
Always contains the value EUR, the only currently supported currency
paymentStatus
enum
The payment status is one of the values balanced, openRevenue, or openExpense
voucherType
enum
Contains the voucher type: salesinvoice, salescreditnote, purchaseinvoice, purchasecreditnote, invoice, downpaymentinvoice, creditnote
voucherStatus
enum
Contains one of the following voucher states: open, paid, paidoff, voided, transferred, sepadebit

Please note that the payment status refers to the underlying voucher type. Due to this, an unbalanced (sales) credit note bears an openRevenue payment status, while an unbalanced purchase credit note is in state openExpense. In addition, voided vouchers behave as paid vouchers and are returned as balanced with a zero open amount.

Further information including total amounts about the voucher is available in the respective endpoints (vouchers, invoices, down-payment-invoices, credit-notes).

Retrieve payment Information

Sample Request

curl https://api.lexoffice.io/v1/payments/1f1dc13c-fd68-11ea-a8b9-ff40c7cabfe0
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "openAmount": "1337.00",
  "currency": "EUR",
  "paymentStatus": "openRevenue",
  "voucherType": "salesinvoice",
  "voucherStatus": "open"
}

GET {resourceurl}/v1/payments/{voucherId}

The following sample shows how to retrieve payment information of a voucher. It is required to replace the placeholder {accessToken} before sending the request.

Payment Conditions Endpoint

Purpose

The payment conditions endpoint provides read access to the list of payment conditions configured in lexoffice.

Payment Conditions properties

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
id
UUID
The payment conditions' identifier
organizationDefault
boolean
True for one payment condition object that was selected by the user as her default, false for all others
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the payment condition.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Retrieve List of Payment Conditions

Sample Request

curl https://api.lexoffice.io/v1/payment-conditions
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

[
    {
        "id": "65be0654-60b6-11eb-b66d-5731dbc9bf6b",
        "paymentTermLabelTemplate": "Zahlbar in {paymentRange} Tagen, rein netto ohne Abzug",
        "paymentTermDuration": 14,
        "organizationDefault": false
    },
    {
        "id": "3fcc62d1-0925-456d-890b-779b56e7289e",
        "paymentTermLabelTemplate": "10 Tage - 3 %, 30 Tage netto",
        "paymentTermDuration": 30,
        "paymentDiscountConditions": {
            "discountRange": 10,
            "discountPercentage": 3.00
        },
        "organizationDefault": true
    }
]

GET {resourceurl}/v1/payment-conditions

The following sample shows how to retrieve list of currently configured payment conditions. It is required to replace the placeholder {accessToken} before sending the request.

Posting Categories Endpoint

Purpose

This endpoint provides read access to the list of posting categories for the (bookkeeping) vouchers revenue or expense which are supported in lexoffice.

Category ids with type income can be used for revenue vouchers such as salesinvoice and salescreditnote and posting categories with type outgo can be applied for expense vouchers with voucher types purchaseinvoice or purchasecreditnote.

Posting Categories Properties

                    Property Description
id
UUID
Unique id of the posting category.
name
string
Name of the posting category.
type
string
Type of the posting category. Possible values are income for revenues and outgo for expenses.
contactRequired
boolean
Flags if a referenced contact is required for this posting category. Possible values are true and false.
splitAllowed
boolean
Flags if items with different tax rate percentages (e.g. 7% and 19%) are allowed for this posting category. Possible values are true and false.
groupName
string
Name of the top level posting category.

Retrieve List of Posting Categories

Sample Request

curl https://api.lexoffice.io/v1/posting-categories
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

[
  {
      "id": "cf03a2b0-f838-474f-ac5e-67adb9b830c7",
      "name": "Reise MA",
      "type": "outgo",
      "contactRequired": false,
      "splitAllowed": true,
      "groupName": "Reisen"
  },
  {
      "id": "3620798f-ae06-4492-b775-1c87eb99247c",
      "name": "Fahrtkosten MA",
      "type": "outgo",
      "contactRequired": false,
      "splitAllowed": true,
      "groupName": "Reisen"
  },
  {
      "id": "8f8664a1-fd86-11e1-a21f-0800200c9a66",
      "name": "Einnahmen",
      "type": "income",
      "contactRequired": false,
      "splitAllowed": true,
      "groupName": "Einnahmen"
  },
  {
      "id": "8f8664a0-fd86-11e1-a21f-0800200c9a66",
      "name": "Dienstleistung",
      "type": "income",
      "contactRequired": false,
      "splitAllowed": true,
      "groupName": "Einnahmen"
  }
]

GET {resourceurl}/v1/posting-categories

The following sample shows how to retrieve list of currently known posting categories. It is required to replace the placeholder {accessToken} before sending the request.

Profile Endpoint

Purpose

The profile endpoint provides read access to basic profile information such as company name, user id, name and email of the connected lexoffice account.

Profile Properties

                    Property Description
organizationId
uuid
Unique id of your company.
companyName
string
Name of your company registered at lexoffice.
created
object
Information about the established connection to lexoffice. For specification of object created please see below.
connectionId
uuid
The id of the current API connection.
taxType
enum
Configured tax type. Possible values are net, gross, and vatfree.
smallBusiness
boolean
Reflects whether the organization is marked as a "small business" (Kleinunternehmer according to §19 UStG.)

Object created Details

                    Property Description
userId
uuid
Unique id of the user who established the connection to lexoffice.
userName
string
The user who established the connection to lexoffice.
userEmail
string
The user's email who established the connection to lexoffice.
date
string
The date when the connection was established in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).

Retrieve Profile Information

Sample Request

curl https://api.lexoffice.io/v1/profile
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "companyName": "Testfirma GmbH",
  "created": {
    "userId": "1aea5501-3f3e-403d-8492-2dad03016289",
    "userName": "Frau Erika Musterfrau",
    "userEmail": "erika.musterfrau@testfirma.de",
    "date": "2017-01-03T13:15:45+0100"
  },
  "connectionId": "3dea098a-fae5-4458-a85c-f97965966c25",
  "features": [
    "cashbox"
  ],
  "subscriptionStatus": "active",
  "taxType": "net",
  "smallBusiness": false
}

GET {resourceurl}/v1/profile

The following sample shows how to retrieve your basic profile information. It is required to replace the placeholder {accessToken} before sending the request.

Quotations Endpoint

Purpose

This endpoint provides read and write access to quotations and also the possibility to render the document as a PDF in order to download it. Quotations can be created as a draft or finalized in open mode.

Please note that Public API connections that were established prior to the release of the quotations endpoint (see Change Log) are not automatically granted the permission for quotations access. Re-generate a new Public API key to benefit from quotations access.

It is possible to create quotations with value-added tax such as of type net (Netto), gross (Brutto) or different types of vat-free. For tax-exempt organizations vat-free (Steuerfrei) quotations can be created exclusively. All other vat-free tax types are only usable in combination with a referenced contact in lexoffice. For recipients within the EU these are intra-community supply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructional services (Bauleistungen gem. §13b UStG) and external services (Fremdleistungen innerhalb der EU gem. §13b UStG). For quotations to third countries, the tax types third party country service (Dienstleistungen an Drittländer) and third party country delivery (Ausfuhrlieferungen an Drittländer) are possible.

Quotations Properties

Sample of a quotation with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
    "id": "424f784e-1f4e-439e-8f71-19673e6d6583",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "createdDate": "2019-12-16T12:43:16.689+01:00",
    "updatedDate": "2019-12-16T15:26:30.074+01:00",
    "version": 4,
    "language": "de",
    "archived": false,
    "voucherStatus": "open",
    "voucherNumber": "AG0006",
    "voucherDate": "2019-12-16T12:43:03.900+01:00",
    "expirationDate": "2020-01-15T12:43:03.900+01:00",
    "address": {
        "contactId": "97c5794f-8ab2-43ad-b459-c5980b055e4d",
        "name": "Berliner Kindl GmbH",
        "street": "Jubiläumsweg 25",
        "city": "Berlin",
        "zip": "14089",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "id": "68569bfc-e5ae-472d-bbdf-6d51a82b1d2f",
            "type": "material",
            "name": "Axa Rahmenschloss Defender RL",
            "description": "Vollständig symmetrisches Design in metallicfarbener Ausführung. Der ergonomische Bedienkopf garantiert die große Benutzerfreundlichkeit dieses Schlosses. Sehr niedrige Kopfhöhe von 46 mm, also mehr Rahmenfreiheit... ",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 20.08,
                "grossAmount": 23.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 23.90,
            "subItems": [
                {
                    "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
                    "type": "material",
                    "name": "Abus Kabelschloss Primo 590 ",
                    "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
                    "quantity": 1,
                    "unitName": "Stück",
                    "unitPrice": {
                        "currency": "EUR",
                        "netAmount": 13.4,
                        "grossAmount": 15.95,
                        "taxRatePercentage": 19
                    },
                    "discountPercentage": 0,
                    "lineItemAmount": 15.95,
                    "alternative": true,
                    "optional": false
                }
            ],
            "alternative": false,
            "optional": false
        },
        {
            "id": "0722bcc6-d1b7-417b-b834-3b47794fa9ab",
            "type": "service",
            "name": "Einfache Montage",
            "description": "Aufwand für einfache Montagetätigkeit",
            "quantity": 1,
            "unitName": "Stunde",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 4.12,
                "grossAmount": 4.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 4.90,
            "alternative": false,
            "optional": true
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 20.08,
        "totalGrossAmount": 23.90,
        "totalTaxAmount": 3.82
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 19,
            "taxAmount": 3.82,
            "netAmount": 20.08
        }
    ],
    "taxConditions": {
        "taxType": "gross"
    },
    "paymentConditions": {
        "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
        "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
        "paymentTermDuration": 30,
        "paymentDiscountConditions": {
            "discountPercentage": 3,
            "discountRange": 10
        }
    },
    "introduction": "Gerne bieten wir Ihnen an:",
    "remark": "Wir freuen uns auf Ihre Auftragserteilung und sichern eine einwandfreie Ausführung zu.",
    "files": {
        "documentFileId": "ebd84e8a-716d-4a20-a76d-21de75a6d3d1"
    },
    "title": "Angebot"
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the quotation belongs to.
Read-only.
createdDate
dateTime
The instant of time when the quotation was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the quotation was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
expirationDate
dateTime
The instant of time when the quotation will expire. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the quotation which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
archived
boolean
Specifies if the quotation is only available in the archive in lexoffice.
Read-only.
voucherStatus
enum
Specifies the status of the quotation. Possible values are draft (is editable), open (finalized and no longer editable but yet neither accepted nor rejected), accepted (has been accepted by the customer), rejected (rejected by the customer)
Read-only.
voucherNumber
string
The specific number a quotation is aware of. This consecutive number is set by lexoffice on creation.
Read-only.
voucherDate
dateTime
The date of quotation in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
address
object
The address of the quotation recipient. For details see below.
lineItems
list
The items of the quotation. For details see below.
totalPrice
object
The total price of the quotation. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the quotation. For details see below.
paymentConditions
object
The payment conditions of the quotation. The organization's (or contact-specific) default is used if no value was send. For details see below.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
files
object
The document id for the PDF version of the quotation. For details see below.
Read-only.

Address Details

There are two main options to address the recipient of a quotation. First, using an existing lexoffice contact or second creating a new address.

For referencing an existing contact it is only necessary to provide the UUID of that contact. Additionally, the referenced address can also be modified for this specific quotation. Therefore all required address fields must be set and the deviated address will not be stored back to the lexoffice contacts.

Otherwise, a new address for the quotation recipient can be created. That type of address is called a "one-time address". A one-time address will not create a new contact in lexoffice. For instance, this could be useful when it is not needed to create a contact in lexoffice for each new quotation.

Please get in touch with us if you are not sure which option fits your use case best.

                    Property Description
contactId
uuid
If the quotation recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the quotation recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.
subItems
List of line item objects
A list of subitems of this line item. At this time, all subItems need to be alternative items.
optional
boolean
If true, the line item is optional ("Optionale Position"). Not a valid attribute for subitems. Defaults to false if unset
alternative
boolean
If true, the line item is an alternative position for its parent item. Currently only valid for subitems, and mandatory to be true in that case. Defaults to false if unset

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the quotation. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Payment Conditions Details

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the quotation.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Files Details

                    Property Description
documentFileId
uuid
The id of the quotation PDF. The PDF will be created when the quotation turns from draft into status open. To download the quotation PDF file please use the files endpoint.

Create a Quotation

Sample Request to create a quotation

curl https://api.lexoffice.io/v1/quotations
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "version": 4,
    "language": "de",
    "voucherDate": "2019-12-16T12:43:03.900+01:00",
    "expirationDate": "2020-01-15T12:43:03.900+01:00",
    "address": {
        "contactId": "97c5794f-8ab2-43ad-b459-c5980b055e4d",
        "name": "Berliner Kindl GmbH",
        "street": "Jubiläumsweg 25",
        "city": "Berlin",
        "zip": "14089",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Axa Rahmenschloss Defender RL",
            "description": "Vollständig symmetrisches Design in metallicfarbener Ausführung. Der ergonomische Bedienkopf garantiert die große Benutzerfreundlichkeit dieses Schlosses. Sehr niedrige Kopfhöhe von 46 mm, also mehr Rahmenfreiheit... ",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 20.08,
                "grossAmount": 23.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 23.90,
            "subItems": [
                {
                    "type": "custom",
                    "name": "Abus Kabelschloss Primo 590 ",
                    "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
                    "quantity": 1,
                    "unitName": "Stück",
                    "unitPrice": {
                        "currency": "EUR",
                        "netAmount": 13.4,
                        "grossAmount": 15.95,
                        "taxRatePercentage": 19
                    },
                    "discountPercentage": 0,
                    "lineItemAmount": 15.95,
                    "alternative": true,
                    "optional": false
                }
            ],
            "alternative": false,
            "optional": false
        },
        {
            "type": "custom",
            "name": "Einfache Montage",
            "description": "Aufwand für einfache Montagetätigkeit",
            "quantity": 1,
            "unitName": "Stunde",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 4.12,
                "grossAmount": 4.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 4.90,
            "alternative": false,
            "optional": true
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 20.08,
        "totalGrossAmount": 23.90,
        "totalTaxAmount": 3.82
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 19,
            "taxAmount": 3.82,
            "netAmount": 20.08
        }
    ],
    "taxConditions": {
        "taxType": "gross"
    },
    "paymentConditions": {
        "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
        "paymentTermDuration": 30,
        "paymentDiscountConditions": {
            "discountPercentage": 3,
            "discountRange": 10
        }
    },
    "introduction": "Gerne bieten wir Ihnen an:",
    "remark": "Wir freuen uns auf Ihre Auftragserteilung und sichern eine einwandfreie Ausführung zu.",
    "title": "Angebot"
}
'

Sample response

{
  "id": "a6d29b44-e5c1-43f2-9403-6859aba4104a",
  "resourceUri": "https://api.lexoffice.io/v1/quotations/a6d29b44-e5c1-43f2-9403-6859aba4104a",
  "createdDate": "2019-12-18T12:37:25.616+01:00",
  "updatedDate": "2019-12-18T12:37:25.616+01:00",
  "version": 1
}

POST {resourceurl}/v1/quotations[?finalize=true]

Quotations transmitted via the API are created in draft mode per default. To create a finalized quotation with status open the optional query parameter finalize has to be set. The status of a quotation cannot be changed via the api.

The created quotation will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers. To provide your end-users access to the created quotation please use our deeplink function.

The contents of the quotation are expected in the request's body as an application/json and must not contain read-only fields.

Description of required properties when creating a quotation.

                    Property Required Notes
voucherDate Yes
expirationDate Yes
address Yes Nested object. Required fields for address please see below.
lineItems Yes List of nested objects. Required fields for lineItems please see below.
totalPrice Yes Nested object. Required fields for totalPrice please see below.
taxConditions Yes Nested object. Required fields for taxConditions see below.

Address Required Properties

Description of required address properties when creating a quotation.

                    Property Required Notes
contactId * Only when referencing an existing lexoffice contact.
name * Only required when no existing contact is referenced.
countryCode * Only required when no existing contact is referenced.

Line Items Required Properties

Description of required lineItem properties when creating a quotation. At this point only line items of type "custom" and "text" are supported.

                    Property Required Notes
type Yes Supported values are custom and text. Other types of line items may be returned by a GET operation.
name Yes
quantity *
unitName *
unitPrice * Nested object. Required fields for unitPrice see below.

Unit Price Required Properties

Description of required unitPrice properties when creating a quotation.

                    Property Required Notes
currency Yes
netAmount * Only relevant if taxConditions.taxType != gross is delivered.
grossAmount * Only relevant if taxConditions.taxType == gross is delivered.
taxRatePercentage Yes Must be 0 for vat-free sales voucher.

Total Price Required Properties

Description of required totalPrice properties when creating a quotation.

                    Property Required Notes
currency Yes

Tax Condition Required Properties

Description of required tax condition properties when creating a quotation.

                    Property Required Notes
taxType Yes Supported values are: gross, net, vatfree, intraCommunitySupply, constructionService13b, externalService13b, thirdPartyCountryService, thirdPartyCountryDelivery.

Retrieve a Quotation

Sample request

curl https://api.lexoffice.io/v1/quotations/424f784e-1f4e-439e-8f71-19673e6d6583
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"

Sample response

{
    "id": "424f784e-1f4e-439e-8f71-19673e6d6583",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "createdDate": "2019-12-16T12:43:16.689+01:00",
    "updatedDate": "2019-12-16T15:26:30.074+01:00",
    "version": 4,
    "language": "de",
    "archived": false,
    "voucherStatus": "open",
    "voucherNumber": "AG0006",
    "voucherDate": "2019-12-16T12:43:03.900+01:00",
    "expirationDate": "2020-01-15T12:43:03.900+01:00",
    "address": {
        "contactId": "97c5794f-8ab2-43ad-b459-c5980b055e4d",
        "name": "Berliner Kindl GmbH",
        "street": "Jubiläumsweg 25",
        "city": "Berlin",
        "zip": "14089",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "id": "68569bfc-e5ae-472d-bbdf-6d51a82b1d2f",
            "type": "material",
            "name": "Axa Rahmenschloss Defender RL",
            "description": "Vollständig symmetrisches Design in metallicfarbener Ausführung. Der ergonomische Bedienkopf garantiert die große Benutzerfreundlichkeit dieses Schlosses. Sehr niedrige Kopfhöhe von 46 mm, also mehr Rahmenfreiheit... ",
            "quantity": 1,
            "unitName": "Stück",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 20.08,
                "grossAmount": 23.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 23.90,
            "subItems": [
                {
                    "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
                    "type": "material",
                    "name": "Abus Kabelschloss Primo 590 ",
                    "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
                    "quantity": 1,
                    "unitName": "Stück",
                    "unitPrice": {
                        "currency": "EUR",
                        "netAmount": 13.4,
                        "grossAmount": 15.95,
                        "taxRatePercentage": 19
                    },
                    "discountPercentage": 0,
                    "lineItemAmount": 15.95,
                    "alternative": true,
                    "optional": false
                }
            ],
            "alternative": false,
            "optional": false
        },
        {
            "id": "0722bcc6-d1b7-417b-b834-3b47794fa9ab",
            "type": "service",
            "name": "Einfache Montage",
            "description": "Aufwand für einfache Montagetätigkeit",
            "quantity": 1,
            "unitName": "Stunde",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 4.12,
                "grossAmount": 4.9,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 4.90,
            "alternative": false,
            "optional": true
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 20.08,
        "totalGrossAmount": 23.90,
        "totalTaxAmount": 3.82
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 19,
            "taxAmount": 3.82,
            "netAmount": 20.08
        }
    ],
    "taxConditions": {
        "taxType": "gross"
    },
    "paymentConditions": {
        "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
        "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
        "paymentTermDuration": 30,
        "paymentDiscountConditions": {
            "discountPercentage": 3,
            "discountRange": 10
        }
    },
    "introduction": "Gerne bieten wir Ihnen an:",
    "remark": "Wir freuen uns auf Ihre Auftragserteilung und sichern eine einwandfreie Ausführung zu.",
    "files": {
        "documentFileId": "ebd84e8a-716d-4a20-a76d-21de75a6d3d1"
    },
    "title": "Angebot"
}

GET {resourceurl}/v1/quotations/{id}

Returns the quotation with id value {id}.

Render a Quotation Document (PDF)

Sample request

curl https://api.lexoffice.io/v1/quotations/e9066f04-8cc7-4616-93f8-ac9ecc8479c8/document
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
  "documentFileId": "b26e1d73-19ff-46b1-8929-09d8d73d4167"
}

GET {resourceurl}/v1/quotations/{id}/document

To download the pdf file of a quotation document, you need its documentFileId. This id is usually returned by the quotation resource. However, newly created quotations in status open via the API have to trigger the pdf document file rendering separately. This can be done with this endpoint.

The returned documentFileId can be used to download the quotation pdf document via the Files Endpoint.

Quotations can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If a quotation is not allowed to be edited, a redirection to the view page takes place. In case the given id does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/quotations/view/{id}

Edit URL {appbaseurl}/permalink/quotations/edit/{id}

Recurring Templates Endpoint

Purpose

This endpoint provides read-only access to the templates of recurring invoices, either individually or all as collection. Based on recurring invoice templates, lexoffice will create regular invoices in configured intervals. This operation is executed at night around 2am CET/CEST.

Please note that it is not possible to query all deduced invoices for a given recurring template. However, when GETting an invoice that was deduced from a recurring template, it will include a reference to the respective recurring template. This allows gathering of information such as the next execution date or the execution status.

Recurring Template Properties

The set of properties of recurring templates are almost the same as of regular invoices, however, recurring templates do not have any date values set because these will only be derived when the recurring invoices are created. Additionally, the configuration of recurring invoices is defined in a nested object. Recurring templates always reference an existing contact.

Sample of a recurring template with multiple line items. Fields with no content are displayed with "null" just for demonstration purposes.

{
  "id": "ac1d66a8-6d59-408b-9413-d56b1db7946f",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "createdDate": "2021-02-10T09:00:00.000+01:00",
  "updatedDate": "2021-02-10T09:00:00.000+01:00",
  "version": 0,
  "language": "de",
  "archived": false,
  "address": {
    "contactId": "464f4881-7a8c-4dc4-87de-7c6fd9a506b8",
    "name": "Bike & Ride GmbH & Co. KG",
    "supplement": "Gebäude 10",
    "street": "Musterstraße 42",
    "city": "Freiburg",
    "zip": "79112",
    "countryCode": "DE"
  },
  "lineItems": [
    {
      "id": "97b98491-e953-4dc9-97a9-ae437a8052b4",
      "type": "material",
      "name": "Abus Kabelschloss Primo 590 ",
      "description": "· 9,5 mm starkes, smoke-mattes Spiralkabel mit integrierter Halterlösung zur Befestigung am Sattelklemmbolzen · bewährter Qualitäts-Schließzylinder mit praktischem Wendeschlüssel · KabelØ: 9,5 mm, Länge: 150 cm",
      "quantity": 2,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 13.4,
        "grossAmount": 15.95,
        "taxRatePercentage": 19
      },
      "discountPercentage": 50,
      "lineItemAmount": 13.4
    },
    {
      "id": "dc4c805b-7df1-4310-a548-22be4499eb04",
      "type": "service",
      "name": "Aufwändige Montage",
      "description": "Aufwand für arbeitsintensive Montagetätigkeit",
      "quantity": 1,
      "unitName": "Stunde",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 8.32,
        "grossAmount": 8.9,
        "taxRatePercentage": 7
      },
      "discountPercentage": 0,
      "lineItemAmount": 8.32
    },
    {
      "id": null,
      "type": "custom",
      "name": "Energieriegel Testpaket",
      "description": null,
      "quantity": 1,
      "unitName": "Stück",
      "unitPrice": {
        "currency": "EUR",
        "netAmount": 5,
        "grossAmount": 5,
        "taxRatePercentage": 0
      },
      "discountPercentage": 0,
      "lineItemAmount": 5
    },
    {
      "type": "text",
      "name": "Freitextposition",
      "description": "This item type can contain either a name or a description or both."
    }
  ],
  "totalPrice": {
    "currency": "EUR",
    "totalNetAmount": 26.72,
    "totalGrossAmount": 29.85,
    "totalTaxAmount": 3.13,
    "totalDiscountAbsolute": null,
    "totalDiscountPercentage": null
  },
  "taxAmounts": [
    {
      "taxRatePercentage": 0,
      "taxAmount": 0,
      "netAmount": 5
    },
    {
      "taxRatePercentage": 7,
      "taxAmount": 0.58,
      "netAmount": 8.32
    },
    {
      "taxRatePercentage": 19,
      "taxAmount": 2.55,
      "netAmount": 13.4
    }
  ],
  "taxConditions": {
    "taxType": "net",
    "taxTypeNote": null
  },
  "paymentConditions": {
    "paymentTermLabel": "10 Tage - 3 %, 30 Tage netto",
    "paymentTermLabelTemplate": "{discountRange} Tage -{discount}, {paymentRange} Tage netto",
    "paymentTermDuration": 30,
    "paymentDiscountConditions": {
      "discountPercentage": 3,
      "discountRange": 10
    }
  },
  "title": "Rechnung",
  "introduction": "Ihre bestellten Positionen stellen wir Ihnen hiermit in Rechnung",
  "remark": "Vielen Dank für Ihren Einkauf",
  "recurringTemplateSettings": {
    "id": "9c5b8bde-7d36-49e8-af5c-4fbe7dc9fa01",
    "startDate": "2021-03-01",
    "endDate": "2021-06-30",
    "finalize": true,
    "shippingType": "service",
    "executionInterval": "MONTHLY",
    "nextExecutionDate": "2021-03-01",
    "lastExecutionFailed": false,
    "lastExecutionErrorMessage": null,
    "executionStatus": "ACTIVE"
  }
}
                    Property Description
id
uuid
Unique id generated on creation by lexoffice.
Read-only.
organizationId
uuid
Unique id of the organization the recurring template belongs to.
Read-only.
createdDate
dateTime
The instant of time when the invoice was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the invoice was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking.
Read-only.
language
string
Specifies the language of the invoice which affects the print document but also set translated default text modules when no values are send (e.g. for introduction). Values accepted in ISO 639-1 code. Possible values are German de (default) and English en.
address
object
The address of the invoice recipient. For details see below.
lineItems
list
The items of the invoice. For details see below.
totalPrice
object
The total price of the invoice. For details see below.
taxAmounts
list
The tax amounts for each tax rate. Please note: As done with every read-only element or object all submitted content (POST) will be ignored. For details see below.
Read-only.
taxConditions
object
The tax conditions of the invoice. For details see below.
paymentConditions
object
The payment conditions of the invoice. The organization's (or contact-specific) default is used if no value was send. For details see below.
title
string
(Optional) A title text. The organization's default is used if no value was sent.
introduction
string
(Optional) An introductory text / header. The organization's default is used if no value was send.
remark
string
(Optional) A closing text note. The organization's default is used if no value was send.
recurringTemplateSettings
object
The settings for creating recurring template.
Read-only.

Address Details

                    Property Description
contactId
uuid
If the recurring-template recipient is (optionally) registered as a contact in lexoffice, this field specifies the related id of the contact.
name
string
The name of the recurring-template recipient. To use an existing contact of an individual person, provide the name in the format {firstname} {lastname}.
supplement
string
(Optional) An address supplement.
street
string
The street (street and street number) of the address.
city
string
The city of the address.
zip
string
The zip code of the address.
countryCode
enum
The ISO 3166 alpha2 country code of the address.
contactPerson
string
The contact person selected while editing the voucher. The primary contact person will be used when creating vouchers via the API with a referenced contactId.
Read-only.

Line Items Details

                    Property Description
id
uuid
The field specifies the related id of the product/service.
Read-only.
type
enum
The type of the item. Possible values are service (the line item is related to a supply of services), material (the line item is related to a physical product), custom (an item without reference in lexoffice and has no id) or text (contains only a name and/or a description for informative purposes).
name
string
The name of the item.
description
string
The description of the item.
quantity
number
The amount of the purchased item. The value can contain up to 4 decimals.
unitName
string
The unit name of the purchased item. If the provided unit name is not known in lexoffice it will be created on the fly.
unitPrice
object
The unit price of the purchased item. For details see below.
discountPercentage
number
The offered discount for the item. The value can contain up to 2 decimals.
lineItemAmount
number
The total price of this line item. Depending by the selected taxType in taxConditions, the amount must be given either as net or gross. The value can contain up to 2 decimals.
Read-only.

Unit Price Details

                    Property Description
currency
enum
The currency of the price. Currently only EUR is supported.
netAmount
number
The net price of the unit price. The value can contain up to 4 decimals.
grossAmount
number
The gross price of the unit price. The value can contain up to 4 decimals.
taxRatePercentage
number
The tax rate of the unit price. Supported tax rates are 0, 5, 7, 16, 19. For vat-free sales vouchers the tax rate percentage must be 0.

Total Price Details

                    Property Description
currency
string
The currency of the total price. Currently only EUR is supported.
totalNetAmount
number
The total net price over all line items. The value can contain up to 2 decimals.
Read-only.
totalGrossAmount
number
The total gross price over all line items. The value can contain up to 2 decimals.
Read-only.
totalTaxAmount
number
The total tax amount over all line items. The value can contain up to 2 decimals.
Read-only.
totalDiscountAbsolute
number
(Optional) A total discount as absolute value. The value can contain up to 2 decimals.
totalDiscountPercentage
number
(Optional) A total discount relative to the gross amount or net amount dependent on the given tax conditions. A contact-specific default will be set if available and no total discount was send. The value can contain up to 2 decimals.

Tax Amounts Details

                    Property Description
taxRatePercentage
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19.
taxAmount
number
The total tax amount for this tax rate. The value can contain up to 2 decimals.
netAmount
number
The total net amount for this tax rate. The value can contain up to 2 decimals.

Tax Conditions Details

Sample for vat-free tax conditions

"taxConditions": {
    "taxType": "constructionService13b",
    "taxTypeNote": "Steuerschuldnerschaft des Leistungsempfängers (Reverse Charge)"
}
                    Property Description
taxType
enum
The tax type for the recurring-template. Possible values are net, gross, vatfree (Steuerfrei), intraCommunitySupply (Innergemeinschaftliche Lieferung gem. §13b UStG), constructionService13b (Bauleistungen gem. §13b UStG), externalService13b (Fremdleistungen innerhalb der EU gem. §13b UStG), thirdPartyCountryService (Dienstleistungen an Drittländer), and thirdPartyCountryDelivery (Ausfuhrlieferungen an Drittländer)
taxTypeNote
string
When taxType is set to a vat-free tax type then a note regarding the conditions can be set. When omitted lexoffice sets the organization's default.

Payment Conditions Details

The payment conditions are optional and the organization's or contact-specific defaults will be used if ommitted.

                    Property Description
paymentTermLabel
string
A textual note regarding the payment conditions.
paymentTermLabelTemplate
string
A textual note regarding the payment conditions. This label template may contain variables such as the discount range. These variables are enclosed in curly braces, e.g., {discountRange}.'
Read-only.
paymentTermDuration
integer
The time left (in days) until the payment must be conducted.
paymentDiscountConditions
list
The payment discount conditions for the recurring-template.

Payment Discount Conditions Details

                    Property Description
discountPercentage
number
The discount offered in return for payment within the discountRange. The value can contain up to 2 decimals.
discountRange
integer
The time left (in days) the discount is valid.

Recurring Template Settings Details

                    Property Description
id
uuid
The id of the recurring template settings.
Read-only.
startDate
date
(Optional) The start date of the first recurring invoice in short iso date yyyy-MM-dd. If null, recurring template is PAUSED.
endDate
date
(Optional) The end date of the first recurring invoice in short iso date yyyy-MM-dd.
finalize
boolean
Specifies the status of the invoice. If false recurring invoices are created as draft (is editable), otherwise they are finalized as open (finalized and no longer editable but yet unpaid or only partially paid). In contrast to the invoice endpoint, finalized recurring invoices will immediately and automatically be sent to the customer via email.
shippingType
enum
The same shipping types defined in the shipping conditions of invoices. Can be either one of: service, serviceperiod, delivery, deliveryperiod, none. The shipping dates/date range will be calculated automatically during execution.
executionInterval
enum
The execution interval defined as WEEKLY, BIWEEKLY, MONTHLY, QUARTERLY, BIANNUALLY, ANNUALLY.
lastExecutionFailed
boolean
Whether the last execution of the recurring template was successful or not.
Read-only.
lastExecutionErrorMessage
string
Describes the problem briefly when the last execution has failed.
Read-only.
executionStatus
enum
The status of the recurring template defined as ACTIVE, PAUSED, ENDED. Note, that there is no error state.
Read-only.



Retrieve a Recurring Template

Sample request

curl https://api.lexoffice.io/v1/recurring-templates/ac1d66a8-6d59-408b-9413-d56b1db7946f
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"

Sample response

{
    "id": "ac1d66a8-6d59-408b-9413-d56b1db7946f",
    "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
    "createdDate": "2021-02-10T14:29:03.114+01:00",
    "updatedDate": "2021-02-10T14:29:03.143+01:00",
    "version": 1,
    "language": "de",
    "archived": false,
    "address": {
        "contactId": "df315523-1e92-473a-9d00-052212da84f8",
        "name": "Haufe-Lexware GmbH & Co. KG",
        "street": "Munzingerstraße 8",
        "city": "Freiburg",
        "zip": "79111",
        "countryCode": "DE"
    },
    "lineItems": [
        {
            "type": "custom",
            "name": "Schulung",
            "quantity": 6,
            "unitName": "Stunde",
            "unitPrice": {
                "currency": "EUR",
                "netAmount": 100.84,
                "grossAmount": 120,
                "taxRatePercentage": 19
            },
            "discountPercentage": 0,
            "lineItemAmount": 720.00
        }
    ],
    "totalPrice": {
        "currency": "EUR",
        "totalNetAmount": 605.04,
        "totalGrossAmount": 720,
        "totalTaxAmount": 114.96
    },
    "taxAmounts": [
        {
            "taxRatePercentage": 19,
            "taxAmount": 114.96,
            "netAmount": 605.04
        }
    ],
    "taxConditions": {
        "taxType": "gross"
    },
    "paymentConditions": {
        "paymentTermLabel": "Zahlbar sofort, rein netto",
        "paymentTermLabelTemplate": "Zahlbar sofort, rein netto",
        "paymentTermDuration": 0
    },
    "introduction": "Unsere Lieferungen/Leistungen stellen wir Ihnen wie folgt in Rechnung.",
    "remark": "Vielen Dank für die gute Zusammenarbeit.",
    "title": "Rechnung",
    "recurringTemplateSettings": {
        ....
    }
}

GET {resourceurl}/v1/recurring-templates/{id}

Returns the recurring template with id value {id}.

Retrieve all Recurring Templates

Sample request

curl https://api.lexoffice.io/v1/recurring-templates?page=0&size=25&sort=createdDate,DESC
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample response

{
    "content": [
        {
            "id": "cab021e5-91d3-4e93-a696-56b7f2417547",
            "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
            "createdDate": "2021-02-10T14:35:40.642+01:00",
            "updatedDate": "2021-02-10T14:36:49.741+01:00",
            "address": {
                "contactId": "464f4881-7a8c-4dc4-87de-7c6fd9a506b8",
                "name": "Bike & Ride GmbH & Co. KG"
            },
            "totalPrice": {
                "currency": "EUR",
                "totalNetAmount": 251.26,
                "totalGrossAmount": 299
            },
            "paymentConditions": {
                "paymentTermLabel": "10 Tage abzüglich 2 % Skonto",
                "paymentTermLabelTemplate": "{paymentRange} Tage abzüglich {discount} Skonto",
                "paymentTermDuration": 10,
                "paymentDiscountConditions": {
                    "discountPercentage": 2,
                    "discountRange": 10
                }
            },
            "recurringTemplateSettings": {
                "id": "615a8db3-bce1-4e11-8302-328fcbacd613",
                "startDate": "2021-04-01",
                "endDate": "2022-04-01",
                "finalize": false,
                "shippingType": "serviceperiod",
                "executionInterval": "QUARTERLY",
                "lastExecutionFailed": false,
                "executionStatus": "PAUSED"
            }
        },
        {
            "id": "ac1d66a8-6d59-408b-9413-d56b1db7946f",
            "organizationId": "a3d94eb4-98bc-429e-b7ad-17f1a8463af9",
            "createdDate": "2021-02-10T14:29:03.114+01:00",
            "updatedDate": "2021-02-10T14:29:03.143+01:00",
            "address": {
                "contactId": "df315523-1e92-473a-9d00-052212da84f8",
                "name": "Haufe-Lexware GmbH & Co. KG"
            },
            "totalPrice": {
                "currency": "EUR",
                "totalNetAmount": 605.04,
                "totalGrossAmount": 720
            },
            "paymentConditions": {
                "paymentTermLabel": "Zahlbar sofort, rein netto",
                "paymentTermLabelTemplate": "Zahlbar sofort, rein netto",
                "paymentTermDuration": 0
            },
            "recurringTemplateSettings": {
                "id": "9c5b8bde-7d36-49e8-af5c-4fbe7dc9fa01",
                "startDate": "2021-03-01",
                "endDate": "2021-06-30",
                "finalize": true,
                "shippingType": "service",
                "executionInterval": "MONTHLY",
                "nextExecutionDate": "2021-03-01",
                "lastExecutionFailed": false,
                "executionStatus": "ACTIVE"
            }
        }
    ],
    "first": true,
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "numberOfElements": 2,
    "size": 25,
    "number": 0,
    "sort": [
        {
            "property": "createdDate",
            "direction": "DESC",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": false
        }
    ]
}

GET {resourceurl}/v1/recurring-templates[?{paging}{&sorting}]

Retrieve a collection of recurring templates. The result returns only part of the most relevant data which are the referenced contact (only id and name), total price, payment conditions and the complete recurring templates settings. The naming of objects and properties are the same, though.

Paging Parameters

The collection of recurring templates is a paged list. This parameter changes the used page size:

                    Parameter Name Description
size Default page size is 25. Can be set up to a maximum of 100.
page Page to retrieve. 0-based value. If not given, the first page (index 0) is returned.

For further information see Paging of Resources

Sorting Parameters

The collection of recurring templates can be sorted using the following parameter:

                    Parameter Name Description
sort Property to sort result content by. Possible values are createdDate, updatedDate, lastExecutionDate or nextExecutionDate. The sort direction can be added separated by a comma. Possible values for the direction are ASC or DESC (default is updatedDate,DESC).

Retrieving the next recurring invoice to be executed

The next recurring template to be executed can be retrieved by using paging and sorting.

GET {resourceurl}/v1/recurring-templates?page=0&size=1&sort=nextExecutionDate,ASC

Recurring templates can be directly accessed by permanent HTTPS links for viewing or editing. In case the given id does not exist, a redirection to the main voucher list takes place.

(There is no separate view page for recurring templates) Edit URL {appbaseurl}/permalink/recurring-templates/edit/{id}

Voucherlist Endpoint

Purpose

The voucherlist endpoint provides read access to meta data of (bookkeeping) vouchers (e.g. salesinvoices, salescreditnotes), invoices (including down payment invoices), credit notes, order confirmations, and quotations. For filters that can be applied to the list see below. Details concerning items from the list are accessible by id using the respective endpoint. For more information on the different voucher types refer to the documentation on the respective endpoints.

Voucherlist Properties

This section describes the properties of the meta data object for vouchers returned by this endpoint.

                    Property Description
id
uuid
Unique id of the voucher in lexoffice.
voucherType
enum
Type of the voucher. Possible values are salesinvoice, salescreditnote, purchaseinvoice, purchasecreditnote, invoice, downpaymentinvoice, creditnote, orderconfirmation, and quotation.
voucherStatus
enum
Showing the current workflow status of the voucher in lexoffice. Possible values are draft, open, paid, paidoff, voided, transferred, sepadebit, overdue, accepted, and rejected.
voucherNumber
string
Identification/Reference number of the voucher.
voucherDate
dateTime
Date when the voucher was issued. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
updatedDate
dateTime
Date when the voucher was last changed (or status changed) in lexoffice. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
dueDate
dateTime
Date when the voucher's payment has to be settled. Value in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
contactName
string
Name of the recipient or invoicing party. Further information on the contact can be retrieved by using the corresponding voucher endpoint (see below).
totalAmount
number
Total amount of the voucher (may include taxes). Format is ##.00 (119.00).
openAmount
number
Open amount of the voucher. May be null (e.g., for invoices in draft, or various non-invoice vouchers). Format is ##.00 (123.00).
currency
enum
Currency of the voucher. Only possible value is EUR.
archived
boolean
Indicates if the voucher is marked as archived in lexoffice.

Filter parameter voucherType

This filter parameter is required. It can contain a comma separated list of voucher types.

Full information on any voucher can be retrieved by calling the endpoint related to the meta data object's voucherType. Please refer to this list for information on which endpoint you should call.

                    Voucher Type Endpoint
salesinvoice Vouchers Endpoint
salescreditnote Vouchers Endpoint
purchaseinvoice Vouchers Endpoint
purchasecreditnote Vouchers Endpoint
invoice Invoices endpoint
creditnote Credit Notes endpoint
orderconfirmation Order Confirmations Endpoint
quotation Quotations Endpoint
downpaymentinvoice Down Payment Invoice Endpoint

Filter parameter voucherStatus

This filter parameter is required. It can contain a comma separated list of voucher status.

                    Voucher Status Description
draft Voucher is created but not yet final. It is still editable in lexoffice.
open Voucher is finalized in lexoffice and no longer editable but yet unpaid or only partially paid.
overdue Voucher is open and dueDate is in the past.
paid Voucher is marked as fully paid in lexoffice.
paidoff Only used for credit notes. Credit note is marked as paidoff in lexoffice.
voided Voucher is cancelled.
transferred Voucher is transferred via the lexoffice online banking connector. When the payment is handled by the bank this status changes to paid.
sepadebit The payment has already been authorized or the amount will be collected by direct debit (direct withdrawal). When the payment is handled by the bank this status changes to paid.
accepted Only used for quotations. This status is set when a quotation was marked as accepted in lexoffice.
rejected Only used for quotations. This status is set when a quotation was marked as rejected in lexoffice.

Filter parameter archived

This filter parameter is optional. If absent the result contains archived and non-archived vouchers.

                    Parameter Name Description
archived (optional) Filter vouchers by archived flag. Possible values are true or false.

Paging parameters

The voucherlist is a paged list. This parameter changes the used page size:

                    Parameter Name Description
size (optional) Default page size is 25. Can be set up to a maximum of 250.

For further information see Paging of Resources

Sorting parameters

The voucherlist can be sorted using the following parameter:

                    Parameter Name Description
sort (optional) Property significant to order of the contents. Possible values are voucherDate, voucherNumber, and updatedDate. The sort direction can be added separated by a comma. Possible values for the direction are ASC or DESC.

Retrieve and filter voucherlist

It is possible to filter vouchers by voucherType, voucherStatus and the archived flag.

Sample Request

curl https://api.lexoffice.io/v1/voucherlist?voucherType=purchaseinvoice,invoice&voucherStatus=open
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
    "content": [
        {
            "id": "57b8d457-1fb6-4ae9-944a-9fe763da2aff",
            "voucherType": "purchaseinvoice",
            "voucherStatus": "open",
            "voucherNumber": "2010096",
            "voucherDate": "2019-06-14T00:00:00.000+02:00",
            "updatedDate": "2019-03-22T12:36:22.000+01:00",
            "dueDate": "2019-06-14T00:00:00.000+02:00",
            "contactName": "Sammellieferant",
            "totalAmount": 80.04,
            "openAmount": 80.04,
            "currency": "EUR",
            "archived": false
        },
        {
            "id": "f3d3ae48-30d9-4b56-973a-b3159cbe743c",
            "voucherType": "invoice",
            "voucherStatus": "open",
            "voucherNumber": "RE1012",
            "voucherDate": "2019-02-14T00:00:00.000+01:00",
            "updatedDate": "2019-03-03T16:52:21.000+01:00",
            "dueDate": "2025-11-13T00:00:00.000+01:00",
            "contactName": "Musterfrau, Erika",
            "totalAmount": 99.8,
            "openAmount": 74.8,
            "currency": "EUR",
            "archived": false
        },
        {
            "id": "55aa6de8-d32d-47bd-9c3c-d541ab65a8e8",
            "voucherType": "invoice",
            "voucherStatus": "overdue",
            "voucherNumber": "RE1011",
            "voucherDate": "2014-10-07T00:00:00.000+02:00",
            "updatedDate": "2017-05-03T16:52:21.000+02:00",
            "dueDate": "2014-11-06T00:00:00.000+01:00",
            "contactName": "Test GmbH",
            "totalAmount": 498.8,
            "openAmount": 498.8,
            "currency": "EUR",
            "archived": false
        }
    ],
    "first": true,
    "last": true,
    "totalPages": 1,
    "totalElements": 3,
    "numberOfElements": 3,
    "size": 25,
    "number": 0,
    "sort": [
        {
            "property": "voucherdate",
            "direction": "DESC",
            "ignoreCase": false,
            "nullHandling": "NATIVE",
            "ascending": false
        }
    ]
}

GET {resourceurl}/v1/voucherlist?{voucherType}&{voucherStatus}&{archived}

Returns a page with meta data on all vouchers of type voucherType, status voucherStatus and marked as archived archived.

Vouchers Endpoint

Purpose

The voucher endpoint provides read/write access to (bookkeeping) sales vouchers (e.g. invoices, creditnotes). For the lexoffice API, write access is currently restricted to sales vouchers, while purchase vouchers can be read.

In contrast to usual invoices which contain item positions, stocks, etc., bookkeeping vouchers are more about bookkeeping and thus this only have positions grouped by tax rate. Optionally, a file (pdf or image) can be added to the voucher as a receipt which was created by an external system.

A higher level description of the handling of vouchers via the lexoffice API can be found in the bookkeeping cookbook (German only).

Voucher Properties

Sample of a voucher having multiple vouchers items with different tax rates and using the collective contact

{
    "id": "a8691b5d-2393-4317-888d-bcd5d564f7d1",
    "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
    "type": "salesinvoice",
    "voucherStatus": "open",
    "voucherNumber": "2016-000321",
    "voucherDate": "2016-06-30T00:00:00.000+02:00",
    "shippingDate": "2016-07-02T00:00:00.000+02:00",
    "dueDate": "2016-07-07T00:00:00.000+02:00",
    "totalGrossAmount": 326.00,
    "totalTaxAmount": 26.00,
    "taxType": "gross",
    "useCollectiveContact": true,
    "remark": "Bestellung von Max Mustermann.",
    "voucherItems": [
        {
            "amount": 119.00,
            "taxAmount": 19.00,
            "taxRatePercent": 19.00,
            "categoryId": "8f8664a8-fd86-11e1-a21f-0800200c9a66"
        },
        {
            "amount": 107.00,
            "taxAmount": 7.00,
            "taxRatePercent": 7.00,
            "categoryId": "8f8664a8-fd86-11e1-a21f-0800200c9a66"
        },
        {
            "amount": 100.00,
            "taxAmount": 0,
            "taxRatePercent": 0.00,
            "categoryId": "8f8664a8-fd86-11e1-a21f-0800200c9a66"
        }
    ],
    "files": [],
    "createdDate": "2016-06-30T13:28:51.012+02:00",
    "updatedDate": "2016-06-30T13:28:51.012+02:00",
    "version": 2
}
                    Property Description
id
uuid
Unique id of the voucher generated on creation by lexoffice.
organizationId
uuid
Unique id of the organization the voucher was generated on.
type
enum
Type of the voucher. Possible values are salesinvoice (e.g. for sales orders), salescreditnote (e.g. for refunds or returned sales orders), purchaseinvoice and purchasecreditnote. Note that the same categoryId can be used for salescreditnotes and for salesinvoices.
voucherStatus
enum
Billing state of the voucher. Possible values are open, paid, paidoff, voided, transferred and sepadebit.
Read-only.
voucherNumber
string
Number of the voucher. Should be the order's identification/reference number.
voucherDate
date
Date when the voucher was issued. Format must be yyyy-MM-dd (e.g. 2016-06-28).
shippingDate
date
Date when the purchased item/service has to be shipped/supplied. If it is a period of time, the end date must be given. Format must be yyyy-MM-dd (e.g. 2016-07-02). Please note: ShippingDate can only be specified for voucher types salesinvoice and salescreditnote.
dueDate
date
Date when the voucher's payment has to be settled. Format must be yyyy-MM-dd (e.g. 2016-06-28).
totalGrossAmount
number
Total gross amount of the voucher. Must match the sum of all positions with added/calculated tax amounts. Format must be ##.00 (119.00).
totalTaxAmount
number
Total tax amount of the voucher. Must match the sum of all positions' tax amounts. Format must be ##.00 (19.00).
taxType
enum
Tax type of the order. Possible values are net (positions amount will be provided net and taxes have to be calculated on top), gross (positions amount will be provided gross and tax is already included).
useCollectiveContact
boolean
Set to true if the Collective Contact (customer/vendor) within lexoffice should be used. If used, the optional contactId will be ignored.
contactId
uuid
If not using the collective contact option, an existing contact id must be provided. This must exist within lexoffice before and can be created via the Contacts endpoint. If a contact is assigned to a voucher, its role must either be Customer, or both Customer and Vendor.
remark
string
Any comments or remarks to the order. This field is part of the full text search of lexoffice, any information for finding the voucher can be placed here as convenience of the lexoffice user.
voucherItems
list
Positions of the voucher grouped by tax rate. Specification of object voucherItems please see below.
files
list
A list of voucher image file uuids. Voucher images can be uploaded and assigned to an existing voucher via the Upload a File to a Voucher sub-resource endpoint. Please note: Each file (voucher image) can only be assigned once.
createdDate
dateTime
The instant of time when the voucher was created by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
updatedDate
dateTime
The instant of time when the voucher was updated by lexoffice in format yyyy-MM-ddTHH:mm:ss.SSSXXX as described in RFC 3339/ISO 8601 (e.g. 2020-02-21T00:00:00.000+01:00).
Read-only.
version
integer
Version (revision) number which will be increased on each change to handle optimistic locking. Set to 0 for initial POST, for PUT get latest version from lexoffice (via GET) and merge with your changes. Please note: If the version did not match the version stored in your system, the user must be informed about losing changes from lexoffice.

Object voucherItems Details

                    Property Description
amount
number
Amount of the position. Net or gross amount, according to the voucher's taxType. Format must be ##.00 (119.00).
taxAmount
number
Tax amount of the voucher's item. Format must be ##.00 (19.00).
taxRatePercent
number
Tax rate as percentage value. Supported tax rates are 0, 5, 7, 16, 19 (e.g. 19).
categoryId
uuid
Booking category for this voucher's revenue or expenditure. Supported and appropriate categoryId's can be found here.

Create a Voucher

Sample Request

curl https://api.lexoffice.io/v1/vouchers
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: application/json"
-H "Accept: application/json"
-d '
{
  "type": "salesinvoice",
  "voucherNumber": "123-456",
  "voucherDate": "2016-06-28",
  "shippingDate": "2016-07-02",
  "dueDate": "2016-07-05",
  "totalGrossAmount": 119.00,
  "totalTaxAmount": 19.00,
  "taxType": "gross",
  "useCollectiveContact": true,
  "remark": "Bestellung von Max Mustermann.",
  "voucherItems": [{
    "amount": 119.00,
    "taxAmount": 19.00,
    "taxRatePercent": 19,
    "categoryId": "8f8664a8-fd86-11e1-a21f-0800200c9a66"
    }]
}'

Sample response

{
  "id": "66196c43-baf3-4335-bfee-d610367059db",
  "resourceUri": "https://api.lexoffice.io/v1/vouchers/66196c43-baf3-4335-bfee-d610367059db",
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

POST {resourceurl}/v1/vouchers

The contents of the voucher are expected in the request's body as an application/json. The contents of the voucher must not contain read-only fields.

The created voucher will be shown in the main voucher list in lexoffice: https://app.lexoffice.de/vouchers.

To provide your end-users access to the created voucher, please use our deeplink function.

Description of required properties when creating a voucher.

                    Property Required Notes
type Yes Possible values are salesinvoice (e.g. for sales orders), and salescreditnote (e.g. for refunds or returned sales orders).
voucherNumber Yes
voucherDate Yes
shippingDate No
dueDate No If not specified then the voucherDate will also be used for dueDate.
totalGrossAmount Yes
totalTaxAmount Yes
taxType Yes
useCollectiveContact * Set to true if the Collective Contact (customer/vendor) within lexoffice should be used. If used, the optional contactId will be ignored.
contactId * If not using the collective contact option, an existing contact id must be provided.
voucherItems Yes List of nested objects. Required fields for voucherItems object please see below.
version Yes

Object voucherItems Details

                    Property Required Notes
amount Yes
taxAmount Yes
taxRatePercent Yes
categoryId Yes

Retrieve a Voucher

Sample Request

curl  https://api.lexoffice.io/v1/vouchers/0a739052-ce80-4ae6-a276-34524eec43b1
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "id": "66196c43-baf3-4335-bfee-d610367059db",
  "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
  "type": "salesinvoice",
  "voucherStatus": "open",
  "voucherNumber": "123-456",
  "voucherDate": "2016-06-28T00:00:00.000+02:00",
  "shippingDate": "2016-07-02T00:00:00.000+02:00",
  "dueDate": "2016-07-05T00:00:00.000+02:00",
  "totalGrossAmount": 119,
  "totalTaxAmount": 19.00,
  "taxType": "gross",
  "useCollectiveContact": true,
  "remark": "Bestellung von Max Mustermann.",
  "voucherItems": [
    {
      "amount": 119,
      "taxAmount": 19.00,
      "taxRatePercent": 19,
      "categoryId": "8f8664a8-fd86-11e1-a21f-0800200c9a66"
    }
  ],
  "files": [],
  "createdDate": "2016-06-29T15:15:09.447+02:00",
  "updatedDate": "2016-06-29T15:15:09.447+02:00",
  "version": 1
}

GET {resourceurl}/v1/vouchers/{id}

Returns the voucher with id value {id}.

Update a Voucher

PUT {resourceurl}/v1/vouchers/{id}.

When you have retrieved a voucher via GET that is identified by {id}, it's possible to update or merge it with the latest information of the requesting system, so that e. g. read-only fields will be filled with the latest lexoffice information - e.g. id, organizationId and version.

Required properties are the same as described in the Create a Voucher section.

Filtering Vouchers

It's possible to filter vouchers by voucherNumber.

Sample Request

curl https://api.lexoffice.io/v1/vouchers?voucherNumber=123-456-789
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "content": [
    {
      "id": "dba9418a-2381-48cd-afa3-81c0c1d0e53e",
      "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
      "type": "purchaseinvoice",
      "voucherNumber": "123-456-789",
      "voucherDate": "2017-01-31T00:00:00.000+01:00",
      "dueDate": "2017-01-31T00:00:00.000+01:00",
      "totalGrossAmount": 1000,
      "totalTaxAmount": 159.66,
      "taxType": "gross",
      "useCollectiveContact": true,
      "remark": "Test",
      "voucherItems": [
        {
          "amount": 1000,
          "taxAmount": 159.66,
          "taxRatePercent": 19,
          "categoryId": "16d04a28-fd91-11e1-a21f-0800200c9a66"
        }
      ],
      "files": [],
      "createdDate": "2017-01-16T07:58:21.849+01:00",
      "updatedDate": "2017-01-16T07:58:21.849+01:00",
      "version": 0
    },
    {
      "id": "0a739052-ce80-4ae6-a276-34524eec43b1",
      "organizationId": "aa93e8a8-2aa3-470b-b914-caad8a255dd8",
      "type": "salesinvoice",
      "voucherNumber": "123-456-789",
      "voucherDate": "2017-01-31T00:00:00.000+01:00",
      "dueDate": "2017-01-31T00:00:00.000+01:00",
      "totalGrossAmount": 500,
      "totalTaxAmount": 79.83,
      "taxType": "gross",
      "useCollectiveContact": true,
      "remark": "Test-2",
      "voucherItems": [
        {
          "amount": 500,
          "taxAmount": 79.83,
          "taxRatePercent": 19,
          "categoryId": "4f01e761-d912-441f-ad1a-1c1d2d590a81"
        }
      ],
      "files": [],
      "createdDate": "2017-01-16T07:59:32.277+01:00",
      "updatedDate": "2017-01-16T07:59:32.277+01:00",
      "version": 0
    }
  ],
  "totalPages": 1,
  "totalElements": 2,
  "last": true,
  "numberOfElements": 2,
  "first": true,
  "size": 25,
  "number": 0
}

GET {resourceurl}/v1/vouchers/?voucherNumber={voucherNumberValue}.

Returns a page with all vouchers where voucherNumber equals a particular value.

Vouchers of type salesinvoice, salescreditnote, purchaseinvoice and purchasecreditnote can be directly accessed by permanent HTTPS links to either be viewed or to be edited. If a voucher is not allowed to be edited, a redirection to the view page takes place. In case the given voucherId does not exist, a redirection to the main voucher list takes place.

View URL {appbaseurl}/permalink/vouchers/view/{voucherId}

Edit URL {appbaseurl}/permalink/vouchers/edit/{voucherId}

Deprecated: View URL {appbaseurl}/vouchers#/view/{voucherId} Edit URL {appbaseurl}/vouchers#/edit/{voucherId}

Upload a File to a Voucher

Sample Request Upload a File to a Voucher

curl https://api.lexoffice.io/v1/vouchers/0a739052-ce80-4ae6-a276-34524eec43b1/files
-X POST
-H "Authorization: Bearer {accessToken}"
-H "Content-Type: multipart/form-data"
-H "Accept: application/json"
-F "file=@{PathToImage}"

POST {resourceurl}/v1/vouchers/{id}/files

Upload a file and assign it directly to the voucher identified by {id}.

The content of the file will be stored in the body of the request. See also files for details about about the required headers. If needed, the file upload status can be retrieved via the files/{id}/status endpoint.

List of CategoryIds

CategoryId's for vouchers of type salesinvoice and salescreditnote

Booking category categoryId
Warenverkäufe 8f8664a8-fd86-11e1-a21f-0800200c9a66
Dienstleistungen 8f8664a0-fd86-11e1-a21f-0800200c9a66
Einnahmen 8f8664a1-fd86-11e1-a21f-0800200c9a66
Innergemeinschaftliche Lieferung 9075a4e3-66de-4795-a016-3889feca0d20
Fremdleistungen §13b 380a20cb-d04c-426e-b49c-84c22adfa362
Ausfuhrlieferungen an Drittländer 93d24c20-ea84-424e-a731-5e1b78d1e6a9
Dienstleistungen an Drittländer ef5b1a6e-f690-4004-9a19-91276348894f
Einnahmen als Kleinunternehmer 7a1efa0e-6283-4cbf-9583-8e88d3ba5960

Paging of Resources

Sample Request

curl https://api.lexoffice.io/v1/contacts/?page=0
-X GET
-H "Authorization: Bearer {accessToken}"
-H "Accept: application/json"

Sample Response

{
  "content":[
    ...
  ],
  "first": true,
  "last": true,
  "totalPages": 1,
  "totalElements": 13,
  "numberOfElements": 13,
  "size": 25,
  "number": 0,
  "sort": [
      {
        "direction": "ASC",
        "property": "name",
        "ignoreCase": false,
        "nullHandling": "NATIVE",
        "ascending": true
      }
  ]
}

The lexoffice API offers basic paging of some of its resources. This page describes the general concept of the paging mechanism in the API. For further details please refer to the specific endpoints. Each paged resource has it own predefined sorting.

Paging Parameters and their names

                 Parameter Name Description
page
integer
Page Pages are zero indexed, thus providing 0 for page will return the first page.
size
integer
Size Default page size is set to 25 but can be increased up to 100/250 (depends on the used endpoint).
sort
string
Sort The default sorting and possible options depends on the used endpoint. Some resources cannot be alternatively sorted (e.g. contacts).

Description of the paging information.

                    Property Description
content
complex
The content of this page as a JSON array.
first
boolean
Whether this page is the first one.
last
boolean
Whether this page is the last one.
totalPages
integer
The total number of pages.
totalElements
integer
The total amount of elements.
numberOfElements
integer
The number of elements in this page.
size
integer
The size of this page.
number
integer
The number of this page. It is always non-negative. Starting with zero.
sort
list
Information on how the content is sorted.

Optimistic Locking

Resource modification with PUT requests in the lexoffice API requires passing a version property, also known as a revision. This is required to mitigate the risk of overwriting data in a data race condition due to concurrent access of the API.

The lexoffice API implements a paradigm known as optimistic locking. That means: an entity (or resource) is not required to be locked before modification, but passing the correct version is required to make sure that no other request has modified the respective entity in the time between the last GET request and the modifying PUT request.

If, for example, a contact is about to be modified, first GET the respective contact, and then include the version you received in your next PUT request. If the record has been modified by someone else in the meantime, you will receive an HTTP status 409 Conflict (see below).

For versioned resources, in the initial POST request, the version needs to have the value of 0.

HTTP Status Codes

The following list shows a brief description of the available HTTP status codes and their meaning in context of the lexoffice API.

                    Response code Description
200
OK
Standard response for a successful request. Depending on the verb (POST, GET, PUT) the response type will be action-result (POST & PUT) or a single entity or a collection of entities (GET).
201
Created
Returned on successful creation of a new resource via POST requests.
202
Accepted
lexoffice has accepted the request. Further processing has to be done. Depending on the used endpoint you can query the processing status.
204
No Content
The resource was successfully deleted.
400
Bad Request
Malformed syntax or a bad query.
401
Unauthorized
Action requires user authentication.
402
Payment Required
Action not accessible due to a lexoffice contract issue. For details see Error Codes.
403
Forbidden
Authenticated but insufficient scope or insufficient access rights in lexoffice.
404
Not Found
Requested resource does no exist (anymore).
405
Not Allowed
Method not allowed on resource.
406
Not Acceptable
Validation issues due to invalid data.
409
Conflict
Indicates that the request is not allowed due to the current state of the resource. For instance, an outdated version field send with PUT.
415
Unsupported Media Type
Missing Content-Type header for POST and PUT requests. Only application/json is supported besides file uploads where multipart/form-data is expected.
429
Too Many Requests
May occur if the endpoint exceeds the limit of throttling. This request should be called again at a later time.
500
Server Error
Internal server error. Please get in contact with us.
501
Not Implemented
Requested HTTP operation not supported.
503
Service Unavailable
Unable to handle the request temporarily.
504
Gateway Timeout
The proxied request from the gateway to the targeted services has timed out. This error occurs when the server did not answer before the request timeout of 30 seconds. It is possible that your request has been processed successfully.

Error Codes

The lexoffice API provides two types of error objects which provide further information in case an error occurs during an API operation.

While extending functionality to the API we also improve the error handling. This happens on behalf of feedback we get from our users and technical aspects.

Authorization and Connection Error Responses

Status Body Cause
401
Unauthorized
{ "message": "Unauthorized" } No token provided, invalid format of authorization token, invalid token or your API client is disabled.
403
Forbidden
{"message": "'{accessToken}' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer {accessToken}'."} Resource not available. Possibly wrong Url or method.
500
Internal Server Error
{ "message": null } lexoffice server not available or internal problem.
503
Service Unavailable
Detail information. May be null. lexoffice server not available.
504
Gateway Timeout
{ "message": "Endpoint request timed out" } Endpoint request timed out. This timeout is set to 30 seconds for all requests.

Legacy error response

Sample for a legacy error response

{
  "IssueList": [
    {
      "i18nKey": "missing_entity",
      "source": "company.name",
      "type": "validation_failure",
      "additionalData": null,
      "args": null
    }
  ]
}

The following REST endpoints are using the legacy error response:

Format of the Error Object

The error object is a JSON object only containing a JSON array named IssueList, which wraps one or more issue objects.

Each issue object contains the attributes i18nKey, source, type, additionalData and args.

Attribute Description
i18nKey error code (human readable)
source Source for this error e.g. the attribute/field that could not be validated. May be null.
type Global type/category
additionalData Detail information. May be null.
args e.g. valid range or locale code. May be null.

Bad Request Errors - Returned with HTTP Status Code 400

i18nKey source type Description
bad_request_error null bad_request_error This error may occur in many cases.
bad_request_error size must be between {MIN_SIZE} and {MAX_SIZE} bad_request_error This error may occur in many cases. In case of the contact filter using email or name, the length of the value is out of range specified by {MIN_SIZE} and {MAX_SIZE}.

Validation Errors - Returned with HTTP Status Code 406

i18nKey source type additionalData args Description
missing_entity attribute name validation_failure null null The value must not be null or empty.

Technical Errors - Returned with HTTP Status Code 500

i18nKey source type additionalData args Description
technical_error error source and contact_vendor_info_not_assigned technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_is_neither_customer_nor_vendor technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_email_address technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_phone_number technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_address technical_error null null The contact has a structural failure. Contact support for further investigations.
technical_error error source and contact_has_not_mappable_country technical_error null null The contact has a structural failure. Contact support for further investigations.

Regular error response

Sample JSON response of type regular error message

{
  "timestamp": "2017-05-11T17:12:31.233+02:00",
  "status": 406,
  "error": "Not Acceptable",
  "path": "/v1/invoices",
  "traceId": "90d78d0777be",
  "message": "Validation failed for request. Please see details list for specific causes.",
  "details": [
    {
      "violation": "NOTNULL",
      "field": "lineItems[0].unitPrice.taxRatePercentage",
      "message": "darf nicht leer sein"
    }
  ]
}

The following REST endpoints are using the regular error response:

Format of the Error Object

The error object is a JSON object.

                    Property Description
timestamp
dateTime
Detailed information about the time when the error has occurred.
status
string
HTTP status code. E.g. 406 in case the payload can´t be accepted because of validation issues. A list of used HTTP status codes can be found here.
error
string
A brief description of the error code.
path
string
Information about the called REST endpoint.
traceId
string
A unique id allowing us to trace the error in our logs.
message
string
Human readable information about the occurred error. This message is not suitable for presenting it to your applications end-users.
details
object
An optional list of additional information about the validation issues.

Description of the Details Object

                    Property Description
violation
string
Information about the type of violation. E.g. NOTNULL indicates a missing data for a mandatory field.
field
string
Name and location of property involved in the validation error.
message
string
Human readable information about the occurred error.
This message is not suitable for presenting it to your application's end-users.

FAQ

Meaning of collective contact (e.g. customer or vendor)

A collective customer / vendor is a concept of a generic contact, against which different bookkeeping actions can be referenced. It can be used, if the user of lexoffice didn't want to create an explicit customer/vendor for each voucher.

In context of the API this means, that an API consumer (Shop-Plugin, App, etc.) can provide a configuration possibility for the user to allow using the collective contact in favor of creating new contacts for each e.g. order.



Getting HTTP Status Code 401

If you retrieve this HTTP status code it is possible, that the lexoffice API is temporarily unavailable which you can verify on the lexoffice status page. Otherwise your request could be missing the authorization header or contain an invalid access token.



URI Components

lexoffice API URI components

The URI components follow the pattern: https://{hostname}/{version}/{resourceUri}{?query}.

Hostname

The host name (base URI) is the first segment of the APIs URI.

{resourceurl}/v1/vouchers

Version

The current API version is v1 and will be changed only if breaking changes are required. See our change log for possible breaking changes.

{resourceurl}/v1/vouchers

Resource URI

The resource URI is the endpoint which provides functionality to create, update and read lexoffice objects.

{resourceurl}/v1/contacts

Query

An optional query string containing key-value pairs separated by a delimiter can used both to filter resources by its property values and control the paging of resources of collections (list of resources).

{resourceurl}/v1/contacts?page=0

Create a lexoffice account

To sign up for a new company, visit https://app.lexoffice.de/signup and click on "Kostenlos registrieren". The signup only requires email and password.

After successful registration check you mailbox for the verification email to confirm the signup.

Get an API key

After signing up for lexoffice, users can generate their private API key at https://app.lexoffice.de/settings/#/public-api.

Gathering organization id

You can get the organization id of your lexoffice account via browser console (open via F12) using the following command:

lxo.organizationId

Gathering contact id(s)

To get the id of an existing contact (e.g. to use it for the invoices endpoint), switch to Kontakte and select the desired contact. When the contact details are shown, the contact's id can be found in the browser's URL field.

https://app.lexoffice.de/master-data/#/contacts/97c5794f-8ab2-43ad-b459-c5980b055e4d

Valid tax rates

During the 2020 corona virus pandemic, the German administration enacted a temporary reduction of the VAT rates (Umsatzsteuer/USt, Mehrwertsteuer/MwSt). The tax rates that lexoffice accepts for the various voucher types depend on the voucherDate of the respective voucher.

Bookkeeping vouchers as managed by the vouchers endpoint may be used with any tax rate valid before, during, and after the tax rate reduction (i.e., with 0%, 5%, 7%, 16%, and 19%).

Vouchers of the quotations, order confirmations, invoices, and credit notes endpoints will only be allowed to use tax rates valid on the relevant date. The relevant date is determined as follows:

An invoice, order confirmation, ... with a relevant date 2020-06-25 may only refer to tax rates 0%, 7%, or 19%; with a relevant date of 2020-07-01, only 0%, 5% and 16% are valid.

XRechnung

XRechnung is a machine readable standardized format for the exchange of invoices and similar vouchers. Invoices addressed to German public authorities may mandatorily be required to be in the XRechnung format.

lexoffice allows the creation of invoices and download of XRechnung XML files.

In order to be able to create an XRechnung for an authorities contact, some prerequisites need to be fulfilled.

The invoice to be created must:

The referenced contact must:

The organization's company data must:

The footer in the print layout must:

Please also find more information here:

Country codes

Lexoffice supports ISO 3166 alpha2 country codes for addresses, e.g. in contacts, or within vouchers etc. However, certain European regions require divergent tax handling, despite being part of a EU country. This includes, e.g., the Spanish Canary Islands.

Support for these countries is provided by extended ISO-3116-2 country codes such as ES_CN (Canary Islands) or GR_69 (Mount Athos).

When called with an invalid country code, endpoints such as the invoices endpoint will report the full list of currently supported country codes.

Samples

The samples for the lexoffice API REST endpoints are provided as a generic Postman collection.

Postman is a free app for API development which allows to easily test REST APIs and supports any type of required "infrastructure". E.g. authorization (basic, token, etc.) as well as header-manipulation, body data, etc.

Importing the samples

The lexoffice samples can be directly imported into Postman via the Import button at the left top (Import File -> Choose Files).

Postman Collection Import

Initial setup

To run the samples via the blue Send button, an "environment" needs to be configured within Postman.

The pre-configured lexoffice environment can be directly imported into Postman via the Manage Environments dropdown at the right top and choosing (Import) in the subsequent dialog.

Postman Environment Import

Accessing endpoints with your API Key

As a first step, you can use Postman to familiarize with the lexoffice API.

Tip: As our sample requests contain an environment variable in the authorization header field, you can add your access token to all requests by updating the accessToken field in the Postman environment to contain your access token.

Postman Bearer Auth Header

Ping Endpoint response

{
    "userEmail": "yourEmail@example.org"
}

After clicking "Send" you should receive a JSON response with the email address of your authorized lexoffice account.

Tip: Postman can generate action basic code in several languages from any sample (e.g. PHP, C#, Java, JavaScript, Ruby, Swift, etc.). Just press the Code link which is located just below the send button.

Postman Code Generation

Change Log

Change log of lexoffice API

Unreleased

(no announcements)

API Changes