> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Lexoffice API reference

> API reference for the Lexoffice plugin in Corsair: every `lexoffice.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Contacts

### create

`contacts.create`

Create a new customer or vendor contact in Lexoffice

**Risk:** `write`

```ts theme={null}
await corsair.lexoffice.api.contacts.create({
	version: 0,
	roles: {
		customer: {},
	},
	person: { lastName: 'Mustermann' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `version` | `number` | No | Defaults to 0. |
| `roles` | `object` | Yes | — |
| `person` | `object` | No | — |
| `company` | `object` | No | — |
| `addresses` | `object` | No | — |
| `emailAddresses` | `object` | No | — |
| `phoneNumbers` | `object` | No | — |
| `xRechnung` | `object` | No | — |
| `note` | `string` | No | — |

New contacts are created with version 0 when omitted and must have exactly one of person or company plus at least one role. Only one entry per address/contact list and one company contact person can be written. XRechnung contacts require both buyerReference and vendorNumberAtCustomer. Personal contact fields are never included in plugin event logs or propagated provider error details.

> [accordion] roles full type
>
> ```ts theme={null}
> {
>   customer?: {
>   },
>   vendor?: {
>   }
> }
> ```

> [accordion] person full type
>
> ```ts theme={null}
> {
>   salutation?: string,
>   firstName?: string,
>   lastName: string
> }
> ```

> [accordion] company full type
>
> ```ts theme={null}
> {
>   name: string,
>   taxNumber?: string,
>   vatRegistrationId?: string,
>   allowTaxFreeInvoices?: boolean,
>   contactPersons?: {
>     salutation?: string,
>     firstName?: string,
>     lastName: string,
>     primary?: boolean,
>     emailAddress?: string,
>     phoneNumber?: string
>   }[]
> }
> ```

> [accordion] addresses full type
>
> ```ts theme={null}
> {
>   billing?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[],
>   shipping?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[]
> }
> ```

> [accordion] emailAddresses full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   private?: string[],
>   other?: string[]
> }
> ```

> [accordion] phoneNumbers full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   mobile?: string[],
>   private?: string[],
>   fax?: string[],
>   other?: string[]
> }
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference?: string,
>   vendorNumberAtCustomer?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***

### get

`contacts.get`

Retrieve a Lexoffice contact by ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.contacts.get({ id: 'c-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `organizationId` | `string` | No | — |
| `version` | `number` | Yes | — |
| `roles` | `object` | No | — |
| `person` | `object` | No | — |
| `company` | `object` | No | — |
| `xRechnung` | `object` | No | — |
| `addresses` | `object` | No | — |
| `emailAddresses` | `object` | No | — |
| `phoneNumbers` | `object` | No | — |
| `note` | `string` | No | — |
| `archived` | `boolean` | No | — |

> [accordion] roles full type
>
> ```ts theme={null}
> {
>   customer?: {
>     number?: number
>   },
>   vendor?: {
>     number?: number
>   }
> }
> ```

> [accordion] person full type
>
> ```ts theme={null}
> {
>   salutation?: string,
>   firstName?: string,
>   lastName: string
> }
> ```

> [accordion] company full type
>
> ```ts theme={null}
> {
>   name: string,
>   taxNumber?: string,
>   vatRegistrationId?: string,
>   allowTaxFreeInvoices?: boolean,
>   contactPersons?: {
>     salutation?: string,
>     firstName?: string,
>     lastName: string,
>     primary?: boolean,
>     emailAddress?: string,
>     phoneNumber?: string
>   }[]
> }
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference?: string,
>   vendorNumberAtCustomer?: string
> }
> ```

> [accordion] addresses full type
>
> ```ts theme={null}
> {
>   billing?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[],
>   shipping?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[]
> }
> ```

> [accordion] emailAddresses full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   private?: string[],
>   other?: string[]
> }
> ```

> [accordion] phoneNumbers full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   mobile?: string[],
>   private?: string[],
>   fax?: string[],
>   other?: string[]
> }
> ```

***

### list

`contacts.list`

List and filter Lexoffice contacts with pagination

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.contacts.list({ page: 0, size: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `email` | `string` | No | — |
| `name` | `string` | No | — |
| `number` | `number` | No | — |
| `customer` | `boolean` | No | — |
| `vendor` | `boolean` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[]` | Yes | — |
| `first` | `boolean` | Yes | — |
| `last` | `boolean` | Yes | — |
| `totalPages` | `number` | Yes | — |
| `totalElements` | `number` | Yes | — |
| `numberOfElements` | `number` | Yes | — |
| `size` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `sort` | `object[]` | No | — |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   id: string,
>   organizationId?: string,
>   version: number,
>   roles?: {
>     customer?: {
>       number?: number
>     },
>     vendor?: {
>       number?: number
>     }
>   },
>   person?: {
>     salutation?: string,
>     firstName?: string,
>     lastName: string
>   },
>   company?: {
>     name: string,
>     taxNumber?: string,
>     vatRegistrationId?: string,
>     allowTaxFreeInvoices?: boolean,
>     contactPersons?: {
>       salutation?: string,
>       firstName?: string,
>       lastName: string,
>       primary?: boolean,
>       emailAddress?: string,
>       phoneNumber?: string
>     }[]
>   },
>   xRechnung?: {
>     buyerReference?: string,
>     vendorNumberAtCustomer?: string
>   },
>   addresses?: {
>     billing?: {
>       supplement?: string,
>       street?: string,
>       city?: string,
>       zip?: string,
>       countryCode: string
>     }[],
>     shipping?: {
>       supplement?: string,
>       street?: string,
>       city?: string,
>       zip?: string,
>       countryCode: string
>     }[]
>   },
>   emailAddresses?: {
>     business?: string[],
>     office?: string[],
>     private?: string[],
>     other?: string[]
>   },
>   phoneNumbers?: {
>     business?: string[],
>     office?: string[],
>     mobile?: string[],
>     private?: string[],
>     fax?: string[],
>     other?: string[]
>   },
>   note?: string,
>   archived?: boolean
> }[]
> ```

> [accordion] sort full type
>
> ```ts theme={null}
> {
>   property?: string,
>   direction?: string,
>   ignoreCase?: boolean,
>   nullHandling?: string,
>   ascending?: boolean
> }[]
> ```

***

### update

`contacts.update`

Update an existing contact in Lexoffice

**Risk:** `write`

```ts theme={null}
await corsair.lexoffice.api.contacts.update({
	id: 'c-00000000-0000-4000-8000-000000000001',
	version: 1,
	roles: {
		customer: {},
	},
	person: { lastName: 'Mustermann' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `version` | `number` | Yes | — |
| `roles` | `object` | Yes | — |
| `person` | `object` | No | — |
| `company` | `object` | No | — |
| `addresses` | `object` | No | — |
| `emailAddresses` | `object` | No | — |
| `phoneNumbers` | `object` | No | — |
| `xRechnung` | `object` | No | — |
| `note` | `string` | No | — |

Updates require the current contact version. Personal contact fields are never included in plugin event logs or propagated provider error details. The same write rules as contacts.create apply: exactly one of person or company, and at least one role.

> [accordion] roles full type
>
> ```ts theme={null}
> {
>   customer?: {
>   },
>   vendor?: {
>   }
> }
> ```

> [accordion] person full type
>
> ```ts theme={null}
> {
>   salutation?: string,
>   firstName?: string,
>   lastName: string
> }
> ```

> [accordion] company full type
>
> ```ts theme={null}
> {
>   name: string,
>   taxNumber?: string,
>   vatRegistrationId?: string,
>   allowTaxFreeInvoices?: boolean,
>   contactPersons?: {
>     salutation?: string,
>     firstName?: string,
>     lastName: string,
>     primary?: boolean,
>     emailAddress?: string,
>     phoneNumber?: string
>   }[]
> }
> ```

> [accordion] addresses full type
>
> ```ts theme={null}
> {
>   billing?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[],
>   shipping?: {
>     supplement?: string,
>     street?: string,
>     city?: string,
>     zip?: string,
>     countryCode: string
>   }[]
> }
> ```

> [accordion] emailAddresses full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   private?: string[],
>   other?: string[]
> }
> ```

> [accordion] phoneNumbers full type
>
> ```ts theme={null}
> {
>   business?: string[],
>   office?: string[],
>   mobile?: string[],
>   private?: string[],
>   fax?: string[],
>   other?: string[]
> }
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference?: string,
>   vendorNumberAtCustomer?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***

## Credit Notes

### create

`creditNotes.create`

Create a credit note, optionally finalizing or pursuing it

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.creditNotes.create({ voucherDate: '2026-01-01', address: { name: 'Acme Corp', countryCode: 'DE' }, lineItems: [{ type: 'custom', name: 'Credit', quantity: 1, unitName: 'piece', unitPrice: { currency: 'EUR', netAmount: 50, taxRatePercentage: 19 } }], totalPrice: { currency: 'EUR' }, taxConditions: { taxType: 'net' } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `finalize` | `boolean` | No | — |
| `precedingSalesVoucherId` | `string` | No | — |
| `voucherDate` | `string` | Yes | — |
| `language` | `de \| en` | No | — |
| `printLayoutId` | `string` | No | — |
| `address` | `object` | Yes | — |
| `lineItems` | `object[]` | Yes | — |
| `totalPrice` | `object` | Yes | — |
| `taxConditions` | `object` | Yes | — |
| `title` | `string` | No | — |
| `introduction` | `string` | No | — |
| `remark` | `string` | No | — |

Credit notes can be finalized or pursued from an existing sales voucher; finalize and precedingSalesVoucherId are query parameters. A finalized credit note related to an invoice is immediately paid off and reduces the invoice's open amount. Credit notes do not support payment conditions, shipping conditions, or per-line discounts. For custom, material, and service lines, name, quantity, unitName, and unitPrice are required; material/service lines also require id.

> [accordion] address full type
>
> ```ts theme={null}
> {
>   contactId?: string,
>   name?: string,
>   supplement?: string,
>   street?: string,
>   city?: string,
>   zip?: string,
>   countryCode?: string
> }
> ```

> [accordion] lineItems full type
>
> ```ts theme={null}
> {
>   type: custom | material | service | text,
>   id?: string,
>   name?: string,
>   description?: string,
>   quantity?: number,
>   unitName?: string,
>   unitPrice?: {
>     currency: EUR,
>     netAmount?: number,
>     grossAmount?: number,
>     taxRatePercentage: number
>   }
> }[]
> ```

> [accordion] totalPrice full type
>
> ```ts theme={null}
> {
>   currency: EUR,
>   totalDiscountAbsolute?: number,
>   totalDiscountPercentage?: number
> }
> ```

> [accordion] taxConditions full type
>
> ```ts theme={null}
> {
>   taxType: net | gross | vatfree | intraCommunitySupply | constructionService13b | externalService13b | thirdPartyCountryService | thirdPartyCountryDelivery | photovoltaicEquipment,
>   taxTypeNote?: string,
>   taxSubType?: distanceSales | electronicServices | null
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***

### download

`creditNotes.download`

Download a credit note document as base64-encoded binary data

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.creditNotes.download({ id: 'cn-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `accept` | `*/* \| application/pdf \| application/xml` | No | — |

Returns the file bytes in base64 form. Lexware supports */*, application/pdf, and application/xml for sales credit notes. For an XRechnung credit note, application/pdf returns only a preview; request application/xml for the e-invoice.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `kind` | `binary` | Yes | — |
| `contentType` | `string` | Yes | — |
| `base64` | `string` | Yes | — |
| `sizeBytes` | `number` | Yes | — |

***

### get

`creditNotes.get`

Retrieve credit note details by ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.creditNotes.get({ id: 'cn-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `organizationId` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | Yes | — |
| `language` | `string` | No | — |
| `archived` | `boolean` | No | — |
| `voucherStatus` | `string` | Yes | — |
| `voucherNumber` | `string \| null` | No | — |
| `voucherDate` | `string` | Yes | — |
| `address` | `object \| null` | No | — |
| `electronicDocumentProfile` | `string` | No | — |
| `lineItems` | `object[]` | No | — |
| `totalPrice` | `object` | Yes | — |
| `taxAmounts` | `object[]` | No | — |
| `taxConditions` | `object` | No | — |
| `relatedVouchers` | `object[]` | No | — |
| `printLayoutId` | `string \| null` | No | — |
| `title` | `string \| null` | No | — |
| `introduction` | `string \| null` | No | — |
| `remark` | `string \| null` | No | — |
| `files` | `object \| null` | No | — |

> [accordion] address full type
>
> ```ts theme={null}
> {
>   contactId?: string | null,
>   name?: string | null,
>   supplement?: string | null,
>   street?: string | null,
>   city?: string | null,
>   zip?: string | null,
>   countryCode?: string | null,
>   contactPerson?: string | null
> } | null
> ```

> [accordion] lineItems full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type: string,
>   name?: string | null,
>   description?: string | null,
>   quantity?: number | null,
>   unitName?: string | null,
>   unitPrice?: {
>     currency: string,
>     netAmount?: number | null,
>     grossAmount?: number | null,
>     taxRatePercentage: number
>   } | null,
>   discountPercentage?: number | null,
>   lineItemAmount?: number | null
> }[]
> ```

> [accordion] totalPrice full type
>
> ```ts theme={null}
> {
>   currency: string,
>   totalNetAmount?: number | null,
>   totalGrossAmount?: number | null,
>   totalTaxAmount?: number | null,
>   totalDiscountAbsolute?: number | null,
>   totalDiscountPercentage?: number | null
> }
> ```

> [accordion] taxAmounts full type
>
> ```ts theme={null}
> {
>   taxRatePercentage: number,
>   taxAmount: number,
>   netAmount: number
> }[]
> ```

> [accordion] taxConditions full type
>
> ```ts theme={null}
> {
>   taxType: string,
>   taxTypeNote?: string | null,
>   taxSubType?: string | null
> }
> ```

> [accordion] relatedVouchers full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherNumber?: string | null,
>   voucherType: string
> }[]
> ```

> [accordion] files full type
>
> ```ts theme={null}
> {
>   documentFileId?: string | null
> } | null
> ```

***

### list

`creditNotes.list`

List credit notes with pagination

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.creditNotes.list({ page: 0, size: 25, voucherStatus: 'open' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `voucherStatus` | `string` | No | — |
| `archived` | `boolean` | No | — |
| `contactId` | `string` | No | — |
| `voucherDateFrom` | `string` | No | — |
| `voucherDateTo` | `string` | No | — |
| `createdDateFrom` | `string` | No | — |
| `createdDateTo` | `string` | No | — |
| `updatedDateFrom` | `string` | No | — |
| `updatedDateTo` | `string` | No | — |
| `voucherNumber` | `string` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |
| `sort` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[]` | Yes | — |
| `first` | `boolean` | Yes | — |
| `last` | `boolean` | Yes | — |
| `totalPages` | `number` | Yes | — |
| `totalElements` | `number` | Yes | — |
| `numberOfElements` | `number` | Yes | — |
| `size` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `sort` | `object[]` | No | — |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   voucherStatus: string,
>   voucherNumber?: string | null,
>   voucherDate?: string | null,
>   createdDate?: string,
>   updatedDate?: string,
>   dueDate?: string | null,
>   contactId?: string | null,
>   contactName?: string | null,
>   totalAmount?: number,
>   openAmount?: number | null,
>   currency?: string,
>   archived?: boolean
> }[]
> ```

> [accordion] sort full type
>
> ```ts theme={null}
> {
>   property?: string,
>   direction?: string,
>   ignoreCase?: boolean,
>   nullHandling?: string,
>   ascending?: boolean
> }[]
> ```

***

### render

`creditNotes.render`

Use the deprecated credit-note document endpoint to retrieve a file ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.creditNotes.render({ id: 'cn-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

Lexware marks this document-ID route deprecated. Prefer creditNotes.download. Finalizing a credit note pursued from an invoice immediately reduces that invoice's open amount.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `documentFileId` | `string` | Yes | — |

***

## Down Payment Invoices

### download

`downPaymentInvoices.download`

Download a down-payment invoice document as base64 data

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.downPaymentInvoices.download({ id: 'dp-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `accept` | `*/* \| application/pdf \| application/xml` | No | — |

Returns document bytes as base64. Draft down-payment invoices do not have a downloadable document. For an XRechnung down-payment invoice, application/pdf returns only a preview; request application/xml for the e-invoice.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `kind` | `binary` | Yes | — |
| `contentType` | `string` | Yes | — |
| `base64` | `string` | Yes | — |
| `sizeBytes` | `number` | Yes | — |

***

### get

`downPaymentInvoices.get`

Retrieve a down-payment invoice by ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.downPaymentInvoices.get({ id: 'dp-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

Down-payment invoices are read-only through this API. Their list metadata is available through voucherlist.list using voucherType=downpaymentinvoice.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `organizationId` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | Yes | — |
| `language` | `string` | No | — |
| `archived` | `boolean` | No | — |
| `voucherStatus` | `string` | Yes | — |
| `voucherNumber` | `string \| null` | No | — |
| `voucherDate` | `string` | Yes | — |
| `dueDate` | `string \| null` | No | — |
| `address` | `object \| null` | No | — |
| `xRechnung` | `object \| null` | No | — |
| `electronicDocumentProfile` | `string` | No | — |
| `lineItems` | `object[]` | No | — |
| `totalPrice` | `object` | Yes | — |
| `taxAmounts` | `object[]` | No | — |
| `taxConditions` | `object` | No | — |
| `paymentConditions` | `object \| null` | No | — |
| `closingInvoice` | `boolean \| null` | No | — |
| `claimedGrossAmount` | `number \| null` | No | — |
| `downPaymentDeductions` | `object[] \| null` | No | — |
| `recurringTemplateId` | `string \| null` | No | — |
| `relatedVouchers` | `object[]` | No | — |
| `printLayoutId` | `string \| null` | No | — |
| `shippingConditions` | `object \| null` | No | — |
| `title` | `string \| null` | No | — |
| `introduction` | `string \| null` | No | — |
| `remark` | `string \| null` | No | — |
| `files` | `object \| null` | No | — |
| `closingInvoiceId` | `string \| null` | No | — |

> [accordion] address full type
>
> ```ts theme={null}
> {
>   contactId?: string | null,
>   name?: string | null,
>   supplement?: string | null,
>   street?: string | null,
>   city?: string | null,
>   zip?: string | null,
>   countryCode?: string | null,
>   contactPerson?: string | null
> } | null
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference?: string | null
> } | null
> ```

> [accordion] lineItems full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type: string,
>   name?: string | null,
>   description?: string | null,
>   quantity?: number | null,
>   unitName?: string | null,
>   unitPrice?: {
>     currency: string,
>     netAmount?: number | null,
>     grossAmount?: number | null,
>     taxRatePercentage: number
>   } | null,
>   discountPercentage?: number | null,
>   lineItemAmount?: number | null
> }[]
> ```

> [accordion] totalPrice full type
>
> ```ts theme={null}
> {
>   currency: string,
>   totalNetAmount?: number | null,
>   totalGrossAmount?: number | null,
>   totalTaxAmount?: number | null,
>   totalDiscountAbsolute?: number | null,
>   totalDiscountPercentage?: number | null
> }
> ```

> [accordion] taxAmounts full type
>
> ```ts theme={null}
> {
>   taxRatePercentage: number,
>   taxAmount: number,
>   netAmount: number
> }[]
> ```

> [accordion] taxConditions full type
>
> ```ts theme={null}
> {
>   taxType: string,
>   taxTypeNote?: string | null,
>   taxSubType?: string | null
> }
> ```

> [accordion] paymentConditions full type
>
> ```ts theme={null}
> {
>   paymentTermLabel?: string | null,
>   paymentTermLabelTemplate?: string | null,
>   paymentTermDuration?: number | null,
>   paymentDiscountConditions?: {
>     discountPercentage: number,
>     discountRange: number
>   } | null
> } | null
> ```

> [accordion] downPaymentDeductions full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   title: string,
>   voucherNumber: string,
>   voucherDate: string,
>   receivedGrossAmount: number,
>   receivedNetAmount: number,
>   receivedTaxAmount: number,
>   taxRatePercentage: number
> }[] | null
> ```

> [accordion] relatedVouchers full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherNumber?: string | null,
>   voucherType: string
> }[]
> ```

> [accordion] shippingConditions full type
>
> ```ts theme={null}
> {
>   shippingDate?: string | null,
>   shippingEndDate?: string | null,
>   shippingType?: string
> } | null
> ```

> [accordion] files full type
>
> ```ts theme={null}
> {
>   documentFileId?: string | null
> } | null
> ```

***

## Files

### download

`files.download`

Download a bookkeeping file as base64-encoded binary data

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.files.download({ id: 'file-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `accept` | `*/* \| application/pdf \| application/xml \| image/jpeg \| image/png` | No | — |

Returns binary bytes as base64. This generic endpoint is intended for bookkeeping voucher files; use the sales-document file routes for invoices, credit notes, and down-payment invoices.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `kind` | `binary` | Yes | — |
| `contentType` | `string` | Yes | — |
| `base64` | `string` | Yes | — |
| `sizeBytes` | `number` | Yes | — |

***

### upload

`files.upload`

Upload a voucher file, which creates a bookkeeping voucher

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.files.upload({ file: 'JVBERi0xLjQK', fileName: 'receipt.pdf', contentType: 'application/pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `file` | `string` | Yes | — |
| `fileName` | `string` | Yes | — |
| `contentType` | `application/pdf \| image/jpeg \| image/png \| application/xml \| text/xml` | Yes | — |

Uses multipart form data with a file part and type=voucher. PDF, JPG, PNG, and XML are documented formats, with a 5 MB maximum. Upload creates a voucher whose OCR processing completes asynchronously. The official reference links to files/\{id}/status but does not publish that route's contract, so status polling is excluded as undocumented.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `voucherId` | `string` | Yes | — |

***

## Invoices

### create

`invoices.create`

Create an invoice in draft or finalized state

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.invoices.create({ voucherDate: '2026-01-01', address: { name: 'Acme Corp', countryCode: 'DE' }, lineItems: [{ type: 'custom', name: 'Consulting', quantity: 1, unitName: 'hour', unitPrice: { currency: 'EUR', netAmount: 100, taxRatePercentage: 19 } }], totalPrice: { currency: 'EUR' }, taxConditions: { taxType: 'net' }, shippingConditions: { shippingType: 'service', shippingDate: '2026-01-01' } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `finalize` | `boolean` | No | — |
| `precedingSalesVoucherId` | `string` | No | — |
| `voucherDate` | `string` | Yes | — |
| `language` | `de \| en` | No | — |
| `printLayoutId` | `string` | No | — |
| `address` | `object` | Yes | — |
| `lineItems` | `object[]` | Yes | — |
| `totalPrice` | `object` | Yes | — |
| `taxConditions` | `object` | Yes | — |
| `paymentConditions` | `object` | No | — |
| `xRechnung` | `object` | No | — |
| `title` | `string` | No | — |
| `introduction` | `string` | No | — |
| `remark` | `string` | No | — |
| `shippingConditions` | `object` | Yes | — |

The operation can finalize a new invoice or pursue a preceding sales voucher; finalize and precedingSalesVoucherId are query parameters. Finalized invoices cannot be edited or deleted via the API. For custom, material, and service lines, name, quantity, unitName, and unitPrice are required; material/service lines also require id. Text lines accept only name and/or description. Net tax conditions require netAmount; gross tax conditions require grossAmount. Shipping conditions and their required dates are validated before sending. `service` and `delivery` need `shippingDate`; `serviceperiod` and `deliveryperiod` need both `shippingDate` and `shippingEndDate`; `none` takes neither.

> [accordion] address full type
>
> ```ts theme={null}
> {
>   contactId?: string,
>   name?: string,
>   supplement?: string,
>   street?: string,
>   city?: string,
>   zip?: string,
>   countryCode?: string
> }
> ```

> [accordion] lineItems full type
>
> ```ts theme={null}
> {
>   type: custom | material | service | text,
>   id?: string,
>   name?: string,
>   description?: string,
>   quantity?: number,
>   unitName?: string,
>   unitPrice?: {
>     currency: EUR,
>     netAmount?: number,
>     grossAmount?: number,
>     taxRatePercentage: number
>   },
>   discountPercentage?: number
> }[]
> ```

> [accordion] totalPrice full type
>
> ```ts theme={null}
> {
>   currency: EUR,
>   totalDiscountAbsolute?: number,
>   totalDiscountPercentage?: number
> }
> ```

> [accordion] taxConditions full type
>
> ```ts theme={null}
> {
>   taxType: net | gross | vatfree | intraCommunitySupply | constructionService13b | externalService13b | thirdPartyCountryService | thirdPartyCountryDelivery | photovoltaicEquipment,
>   taxTypeNote?: string,
>   taxSubType?: distanceSales | electronicServices | null
> }
> ```

> [accordion] paymentConditions full type
>
> ```ts theme={null}
> {
>   paymentTermLabel?: string,
>   paymentTermDuration?: number,
>   paymentDiscountConditions?: {
>     discountPercentage: number,
>     discountRange: number
>   }
> }
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference: string
> }
> ```

> [accordion] shippingConditions full type
>
> ```ts theme={null}
> {
>   shippingDate?: string,
>   shippingEndDate?: string,
>   shippingType: service | serviceperiod | delivery | deliveryperiod | none
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***

### download

`invoices.download`

Download an invoice document as base64-encoded binary data

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.invoices.download({ id: 'i-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `accept` | `*/* \| application/pdf \| application/xml` | No | — |

Returns the file bytes in base64 form. Lexware supports */*, application/pdf, and application/xml for sales invoices; XRechnung PDF output is a preview only.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `kind` | `binary` | Yes | — |
| `contentType` | `string` | Yes | — |
| `base64` | `string` | Yes | — |
| `sizeBytes` | `number` | Yes | — |

***

### get

`invoices.get`

Retrieve invoice details by ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.invoices.get({ id: 'i-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `organizationId` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | Yes | — |
| `language` | `string` | No | — |
| `archived` | `boolean` | No | — |
| `voucherStatus` | `string` | Yes | — |
| `voucherNumber` | `string \| null` | No | — |
| `voucherDate` | `string` | Yes | — |
| `dueDate` | `string \| null` | No | — |
| `address` | `object \| null` | No | — |
| `xRechnung` | `object \| null` | No | — |
| `electronicDocumentProfile` | `string` | No | — |
| `lineItems` | `object[]` | No | — |
| `totalPrice` | `object` | Yes | — |
| `taxAmounts` | `object[]` | No | — |
| `taxConditions` | `object` | No | — |
| `paymentConditions` | `object \| null` | No | — |
| `closingInvoice` | `boolean \| null` | No | — |
| `claimedGrossAmount` | `number \| null` | No | — |
| `downPaymentDeductions` | `object[] \| null` | No | — |
| `recurringTemplateId` | `string \| null` | No | — |
| `relatedVouchers` | `object[]` | No | — |
| `printLayoutId` | `string \| null` | No | — |
| `shippingConditions` | `object \| null` | No | — |
| `title` | `string \| null` | No | — |
| `introduction` | `string \| null` | No | — |
| `remark` | `string \| null` | No | — |
| `files` | `object \| null` | No | — |

> [accordion] address full type
>
> ```ts theme={null}
> {
>   contactId?: string | null,
>   name?: string | null,
>   supplement?: string | null,
>   street?: string | null,
>   city?: string | null,
>   zip?: string | null,
>   countryCode?: string | null,
>   contactPerson?: string | null
> } | null
> ```

> [accordion] xRechnung full type
>
> ```ts theme={null}
> {
>   buyerReference?: string | null
> } | null
> ```

> [accordion] lineItems full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type: string,
>   name?: string | null,
>   description?: string | null,
>   quantity?: number | null,
>   unitName?: string | null,
>   unitPrice?: {
>     currency: string,
>     netAmount?: number | null,
>     grossAmount?: number | null,
>     taxRatePercentage: number
>   } | null,
>   discountPercentage?: number | null,
>   lineItemAmount?: number | null
> }[]
> ```

> [accordion] totalPrice full type
>
> ```ts theme={null}
> {
>   currency: string,
>   totalNetAmount?: number | null,
>   totalGrossAmount?: number | null,
>   totalTaxAmount?: number | null,
>   totalDiscountAbsolute?: number | null,
>   totalDiscountPercentage?: number | null
> }
> ```

> [accordion] taxAmounts full type
>
> ```ts theme={null}
> {
>   taxRatePercentage: number,
>   taxAmount: number,
>   netAmount: number
> }[]
> ```

> [accordion] taxConditions full type
>
> ```ts theme={null}
> {
>   taxType: string,
>   taxTypeNote?: string | null,
>   taxSubType?: string | null
> }
> ```

> [accordion] paymentConditions full type
>
> ```ts theme={null}
> {
>   paymentTermLabel?: string | null,
>   paymentTermLabelTemplate?: string | null,
>   paymentTermDuration?: number | null,
>   paymentDiscountConditions?: {
>     discountPercentage: number,
>     discountRange: number
>   } | null
> } | null
> ```

> [accordion] downPaymentDeductions full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   title: string,
>   voucherNumber: string,
>   voucherDate: string,
>   receivedGrossAmount: number,
>   receivedNetAmount: number,
>   receivedTaxAmount: number,
>   taxRatePercentage: number
> }[] | null
> ```

> [accordion] relatedVouchers full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherNumber?: string | null,
>   voucherType: string
> }[]
> ```

> [accordion] shippingConditions full type
>
> ```ts theme={null}
> {
>   shippingDate?: string | null,
>   shippingEndDate?: string | null,
>   shippingType?: string
> } | null
> ```

> [accordion] files full type
>
> ```ts theme={null}
> {
>   documentFileId?: string | null
> } | null
> ```

***

### list

`invoices.list`

List outgoing invoices with pagination

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.invoices.list({ page: 0, size: 25, voucherStatus: 'open' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `voucherStatus` | `string` | No | — |
| `archived` | `boolean` | No | — |
| `contactId` | `string` | No | — |
| `voucherDateFrom` | `string` | No | — |
| `voucherDateTo` | `string` | No | — |
| `createdDateFrom` | `string` | No | — |
| `createdDateTo` | `string` | No | — |
| `updatedDateFrom` | `string` | No | — |
| `updatedDateTo` | `string` | No | — |
| `voucherNumber` | `string` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |
| `sort` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[]` | Yes | — |
| `first` | `boolean` | Yes | — |
| `last` | `boolean` | Yes | — |
| `totalPages` | `number` | Yes | — |
| `totalElements` | `number` | Yes | — |
| `numberOfElements` | `number` | Yes | — |
| `size` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `sort` | `object[]` | No | — |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   voucherStatus: string,
>   voucherNumber?: string | null,
>   voucherDate?: string | null,
>   createdDate?: string,
>   updatedDate?: string,
>   dueDate?: string | null,
>   contactId?: string | null,
>   contactName?: string | null,
>   totalAmount?: number,
>   openAmount?: number | null,
>   currency?: string,
>   archived?: boolean
> }[]
> ```

> [accordion] sort full type
>
> ```ts theme={null}
> {
>   property?: string,
>   direction?: string,
>   ignoreCase?: boolean,
>   nullHandling?: string,
>   ascending?: boolean
> }[]
> ```

***

### render

`invoices.render`

Use the deprecated invoice document endpoint to retrieve a file ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.invoices.render({ id: 'i-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

Lexware marks this document-ID route deprecated. Prefer invoices.download, which returns the document bytes directly. Draft invoices have no downloadable document.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `documentFileId` | `string` | Yes | — |

***

## Payments

### get

`payments.get`

Retrieve payment status and payment entries for a voucher

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.payments.get({ voucherId: 'i-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `voucherId` | `string` | Yes | — |

Retrieves payment status for a voucher ID; the API documents this operation as read-only.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `openAmount` | `number \| string` | Yes | — |
| `currency` | `string` | Yes | — |
| `paymentStatus` | `string` | Yes | — |
| `voucherType` | `string` | Yes | — |
| `voucherStatus` | `string` | Yes | — |
| `paidDate` | `string` | No | — |
| `paymentItems` | `object[]` | Yes | — |

> [accordion] paymentItems full type
>
> ```ts theme={null}
> {
>   paymentItemType: string,
>   postingDate: string,
>   amount: number,
>   currency: string
> }[]
> ```

***

## Posting Categories

### list

`postingCategories.list`

List the available bookkeeping posting categories

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.postingCategories.list({});
```

**Input:** *empty object*

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   id: string,
>   name: string,
>   type: income | outgo,
>   contactRequired: boolean,
>   splitAllowed: boolean,
>   groupName: string
> }[]
> ```

***

## Profile

### get

`profile.get`

Retrieve organization and account profile details

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.profile.get({});
```

**Input:** *empty object*

The response includes organization/account profile details and may include the account user's email as returned by the provider. The plugin does not log the response.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `organizationId` | `string` | Yes | — |
| `companyName` | `string` | No | — |
| `created` | `object` | No | — |
| `connectionId` | `string` | No | — |
| `taxType` | `net \| gross \| vatfree` | No | — |
| `distanceSalesPrinciple` | `ORIGIN \| DESTINATION` | No | — |
| `businessFeatures` | `string[]` | No | — |
| `features` | `string[]` | No | — |
| `subscriptionStatus` | `string` | No | — |
| `smallBusiness` | `boolean` | No | — |

> [accordion] created full type
>
> ```ts theme={null}
> {
>   userId?: string,
>   userName?: string,
>   userEmail?: string,
>   date?: string
> }
> ```

***

## Voucherlist

### list

`voucherlist.list`

Search all documented Lexware voucher types with paging

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.voucherlist.list({ voucherType: 'invoice,creditnote', voucherStatus: 'any', page: 0, size: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `voucherType` | `string` | Yes | — |
| `voucherStatus` | `string` | Yes | — |
| `archived` | `boolean` | No | — |
| `contactId` | `string` | No | — |
| `voucherDateFrom` | `string` | No | — |
| `voucherDateTo` | `string` | No | — |
| `createdDateFrom` | `string` | No | — |
| `createdDateTo` | `string` | No | — |
| `updatedDateFrom` | `string` | No | — |
| `updatedDateTo` | `string` | No | — |
| `voucherNumber` | `string` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |
| `sort` | `string` | No | — |

voucherType and voucherStatus are required; use any or documented comma-separated values. Pagination is zero-based with a maximum size of 250. Invoice, credit-note, and down-payment invoice list operations use this route. `overdue` must be used on its own; it cannot be combined with other statuses.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[]` | Yes | — |
| `first` | `boolean` | Yes | — |
| `last` | `boolean` | Yes | — |
| `totalPages` | `number` | Yes | — |
| `totalElements` | `number` | Yes | — |
| `numberOfElements` | `number` | Yes | — |
| `size` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `sort` | `object[]` | No | — |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   voucherStatus: string,
>   voucherNumber?: string | null,
>   voucherDate?: string | null,
>   createdDate?: string,
>   updatedDate?: string,
>   dueDate?: string | null,
>   contactId?: string | null,
>   contactName?: string | null,
>   totalAmount?: number,
>   openAmount?: number | null,
>   currency?: string,
>   archived?: boolean
> }[]
> ```

> [accordion] sort full type
>
> ```ts theme={null}
> {
>   property?: string,
>   direction?: string,
>   ignoreCase?: boolean,
>   nullHandling?: string,
>   ascending?: boolean
> }[]
> ```

***

## Vouchers

### attachFile

`vouchers.attachFile`

Upload a bookkeeping document to an existing voucher

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.vouchers.attachFile({ id: 'v-00000000-0000-4000-8000-000000000001', file: 'JVBERi0xLjQK', fileName: 'receipt.pdf', contentType: 'application/pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `file` | `string` | Yes | — |
| `fileName` | `string` | Yes | — |
| `contentType` | `application/pdf \| image/jpeg \| image/png \| application/xml \| text/xml` | Yes | — |

Uploads a file to an existing voucher. This request has no type form field; use files.upload to create a voucher from an uploaded receipt.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

***

### create

`vouchers.create`

Create a new bookkeeping voucher

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.vouchers.create({ type: 'purchaseinvoice', voucherNumber: 'PUR-2026-001', voucherDate: '2026-01-01', totalGrossAmount: 119, totalTaxAmount: 19, taxType: 'net', useCollectiveContact: true, voucherItems: [{ amount: 100, taxAmount: 19, taxRatePercent: 19, categoryId: 'efa82f49-fd85-11e1-a21f-0800200c9a66' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `salesinvoice \| salescreditnote \| purchaseinvoice \| purchasecreditnote` | Yes | — |
| `voucherStatus` | `open \| unchecked` | No | — |
| `voucherNumber` | `string` | No | — |
| `voucherDate` | `string` | No | — |
| `shippingDate` | `string` | No | — |
| `dueDate` | `string` | No | — |
| `totalGrossAmount` | `number` | No | — |
| `totalTaxAmount` | `number` | No | — |
| `taxType` | `net \| gross \| vatfree` | Yes | — |
| `useCollectiveContact` | `boolean` | No | — |
| `contactId` | `string` | No | — |
| `contactName` | `string` | No | — |
| `remark` | `string` | No | — |
| `voucherItems` | `object[]` | No | — |
| `files` | `string[]` | No | — |
| `version` | `number` | No | — |

For an open voucher, supply voucherNumber, totalGrossAmount, totalTaxAmount, each item's taxAmount, and either contactId or useCollectiveContact: true. If both contact fields are supplied, Lexware ignores contactId when useCollectiveContact is true. The purchase example uses the documented "Reisen (für Selbständige)" expense category; select an appropriate outgo category from postingCategories.list for the actual expense. Version is omitted unless explicitly provided because the provider's create documentation conflicts about its initial value. Leaving out `voucherStatus` creates an `open` voucher, which also needs `voucherDate` and at least one entry in `voucherItems`.

> [accordion] voucherItems full type
>
> ```ts theme={null}
> {
>   amount: number,
>   taxAmount: number,
>   taxRatePercent: number,
>   categoryId: string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***

### get

`vouchers.get`

Retrieve voucher details by ID

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.vouchers.get({ id: 'v-00000000-0000-4000-8000-000000000001' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   id: string,
>   organizationId?: string,
>   createdDate?: string,
>   updatedDate?: string,
>   type: string,
>   voucherNumber?: string | null,
>   shippingDate?: string | null,
>   dueDate?: string | null,
>   totalGrossAmount?: number | null,
>   totalTaxAmount?: number | null,
>   taxType?: string | null,
>   useCollectiveContact?: boolean,
>   contactId?: string | null,
>   contactName?: string | null,
>   remark?: string | null,
>   files?: string[],
>   version: number,
>   voucherStatus: unchecked,
>   voucherDate?: string | null,
>   voucherItems?: {
>     amount: number,
>     taxAmount?: number,
>     taxRatePercent: number,
>     categoryId: string
>   }[] | null
> } | {
>   id: string,
>   organizationId?: string,
>   createdDate?: string,
>   updatedDate?: string,
>   type: string,
>   voucherNumber?: string | null,
>   shippingDate?: string | null,
>   dueDate?: string | null,
>   totalGrossAmount?: number | null,
>   totalTaxAmount?: number | null,
>   taxType?: string | null,
>   useCollectiveContact?: boolean,
>   contactId?: string | null,
>   contactName?: string | null,
>   remark?: string | null,
>   files?: string[],
>   version: number,
>   voucherStatus: string,
>   voucherDate: string,
>   voucherItems: {
>     amount: number,
>     taxAmount?: number,
>     taxRatePercent: number,
>     categoryId: string
>   }[]
> }
> ```

***

### list

`vouchers.list`

List bookkeeping vouchers with optional voucher number filter

**Risk:** `read`

```ts theme={null}
await corsair.lexoffice.api.vouchers.list({ voucherNumber: 'PUR-2026-001', page: 0, size: 25 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `voucherNumber` | `string` | No | — |
| `page` | `number` | No | — |
| `size` | `number` | No | — |

This convenience operation filters bookkeeping voucher types and voucherStatus=any through the current /voucherlist route. Lexware's older /vouchers?voucherNumber filter is deprecated.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[]` | Yes | — |
| `first` | `boolean` | Yes | — |
| `last` | `boolean` | Yes | — |
| `totalPages` | `number` | Yes | — |
| `totalElements` | `number` | Yes | — |
| `numberOfElements` | `number` | Yes | — |
| `size` | `number` | Yes | — |
| `number` | `number` | Yes | — |
| `sort` | `object[]` | No | — |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   id: string,
>   voucherType: string,
>   voucherStatus: string,
>   voucherNumber?: string | null,
>   voucherDate?: string | null,
>   createdDate?: string,
>   updatedDate?: string,
>   dueDate?: string | null,
>   contactId?: string | null,
>   contactName?: string | null,
>   totalAmount?: number,
>   openAmount?: number | null,
>   currency?: string,
>   archived?: boolean
> }[]
> ```

> [accordion] sort full type
>
> ```ts theme={null}
> {
>   property?: string,
>   direction?: string,
>   ignoreCase?: boolean,
>   nullHandling?: string,
>   ascending?: boolean
> }[]
> ```

***

### update

`vouchers.update`

Update a bookkeeping voucher including its assigned files

**Risk:** `destructive`

```ts theme={null}
await corsair.lexoffice.api.vouchers.update({ id: 'v-00000000-0000-4000-8000-000000000001', version: 3, files: ['f-00000000-0000-4000-8000-000000000001'], type: 'purchaseinvoice', voucherNumber: 'PUR-2026-001', voucherDate: '2026-01-01', totalGrossAmount: 119, totalTaxAmount: 19, taxType: 'net', useCollectiveContact: true, voucherItems: [{ amount: 100, taxAmount: 19, taxRatePercent: 19, categoryId: 'efa82f49-fd85-11e1-a21f-0800200c9a66' }] });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `version` | `number` | Yes | — |
| `type` | `salesinvoice \| salescreditnote \| purchaseinvoice \| purchasecreditnote` | Yes | — |
| `voucherStatus` | `open \| unchecked` | No | — |
| `voucherNumber` | `string` | Yes | — |
| `voucherDate` | `string` | Yes | — |
| `shippingDate` | `string` | No | — |
| `dueDate` | `string` | No | — |
| `totalGrossAmount` | `number` | Yes | — |
| `totalTaxAmount` | `number` | Yes | — |
| `taxType` | `net \| gross \| vatfree` | Yes | — |
| `useCollectiveContact` | `boolean` | No | — |
| `contactId` | `string` | No | — |
| `contactName` | `string` | No | — |
| `remark` | `string` | No | — |
| `voucherItems` | `object[]` | Yes | — |
| `files` | `string[]` | Yes | — |

Updates require the latest version and the existing files array. Lexware warns that omitting existing file IDs permanently deletes those files. voucherStatus can only be changed from unchecked to open; this operation is classified destructive. `voucherDate` is written as YYYY-MM-DD: take the date part of the timestamp `vouchers.get` returns (for example `2026-11-21` from `2026-11-21T00:00:00.000+01:00`) without converting it to UTC. Read the voucher first and pass its `version` and every file ID in `files`.

> [accordion] voucherItems full type
>
> ```ts theme={null}
> {
>   amount: number,
>   taxAmount: number,
>   taxRatePercent: number,
>   categoryId: string
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `resourceUri` | `string` | No | — |
| `createdDate` | `string` | No | — |
| `updatedDate` | `string` | No | — |
| `version` | `number` | No | — |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.