Between an order in the shop and an invoice in the books, many companies still have an export, a spreadsheet and an afternoon. The public interface of Lexware Office accepts vouchers and articles directly, but it does so on its own terms: two requests per second (Lexware), at most 300 line items per voucher (Lexware) and only EUR as the currency (Lexware). Knowing these edges before the first call produces a route that also holds up in the Christmas season. Discovering them in production means building it twice.
Key takeaways
- The interface paces, it does not queue: an integration may make up to two requests per second (Lexware). If the rate exceeds that cap, HTTP 429 comes back and the call is not executed at all (Lexware).
- A voucher holds at most 300 line items (Lexware). Collective invoices with many tiny positions are split or condensed beforehand, otherwise the transfer fails on the limit rather than on the content.
- The article master is tightly bounded: the permitted tax rates are 0, 7 and 19 (Lexware), the GTIN is validated against GTIN-8, GTIN-12, GTIN-13 and GTIN-14 (Lexware), and settlement is in only EUR (Lexware).
- Whether a transferred invoice becomes an e-invoice is steered by the contact, not by a field on the voucher: electronicDocumentProfile reports the produced profile, that is NONE, EN16931 or XRechnung, and is read-only (Lexware). That is where the integration meets VAT law.
- The voucher route does not end when the invoice is sent: accounting vouchers must be retained for eight years (German Fiscal Code), and VAT law repeats the same period independently for invoices (German VAT Act).
What the interface allows and what it rejects
An integration rarely begins with the question of what a system can do. It begins with the question of where it stops, because the limits determine the architecture, not the wish list. With Lexware Office these limits are documented explicitly and are therefore predictable. The most important one comes right at the start: an integration may make up to two requests per second (Lexware). That sounds generous as long as you are thinking of individual orders. It gets tight as soon as a catalogue synchronisation has to check several thousand articles, and it becomes an architectural question as soon as the shop works through an order peak.
The second sentence matters more than the first: if the rate of incoming requests exceeds the available limits, HTTP 429 comes back and the call is not executed (Lexware). So the interface does not buffer, it rejects. For the integration this means that the pacing belongs on your own side. A queue with a fixed drain rate is the usual answer, and it has to be able to repeat a rejected call without booking it twice. Whether that succeeds without duplicate vouchers depends on a clean key per transaction; the pattern is the same as with idempotency and retry strategies on any other interface.
| Limit | Value in the documentation | What follows from it |
|---|---|---|
| Requests per second | 2 (Lexware) | Pacing on your own side, no batch bursts |
| Response when exceeded | HTTP 429, call not executed (Lexware) | Retry with growing pause, transaction key per voucher |
| Line items per voucher | at most 300 (Lexware) | Split collective vouchers or condense line items |
| Page size of lists | 25 by default, up to 250 (Lexware) | Set the page size, otherwise 200 calls instead of 20 |
| Search window of the voucher list | 10,000 entries (Lexware) | Split the synchronisation into time slices and keep a marker |
| Attachment per voucher | 5 MB (Lexware) | Shrink the PDF before transfer and check its size |
| Read timeout of the callback | 5,000 ms (Lexware) | The callback accepts and processes afterwards |
Two of these rows are regularly overlooked. The default page of a list is set to 25 entries and can be raised to 100 or 250 depending on the endpoint (Lexware). Miss that, and a stock of 5,000 articles is fetched in 200 calls instead of 20, which puts you straight back against the cap of two requests per second. And across all pages the voucher list returns a window of only 10,000 entries (Lexware). A synchronisation across a full financial year therefore does not run as one pass, but as a sequence of time slices, month by month, with a marker recording how far you got.
The endpoint changed its name
The voucher route: from order to invoice
An order in the shop is not yet a voucher. It only becomes one when its content is mapped onto the fields that the accounting system keeps, and that mapping is the real work of the integration. The header of the voucher carries date, customer, address and tax logic. The line items carry quantity, unit, net price, tax rate and the link to the article master. The totals level carries net, tax and gross, plus a currency that knows exactly one value: the interface currently supports only EUR (Lexware). A shop that settles in francs or pounds converts before the transfer and records the rate on the voucher, otherwise the figure can no longer be explained later.
The second edge sits with the line items. A voucher holds at most 300 line items (Lexware), and according to the documentation the same limit applies to credit notes, order confirmations, delivery notes and quotations. For a classic single order that is plenty. For a monthly collective invoice of a B2B customer with daily small call-offs it is not. Two routes get past it: split the collective voucher at an edge that makes business sense, per delivery or per cost centre for example, or condense identical articles into one line item with a total quantity. Both are business decisions, not technical ones; they belong before the first call and not in the exception branch.
shop.order -> lexware.invoice
order_number -> introduction # free text; voucherNumber set by Lexware
order_date -> voucherDate
customer.id -> address.contactId # else address.name + address
currency -> totalPrice.currency # EUR only
line_items[] -> lineItems[] # max. 300
article_number -> id (article link) or name + description
quantity -> quantity
unit -> unitName
unit_price_net -> unitPrice.netAmount
tax_rate -> unitPrice.taxRatePercentage
shipping_cost -> lineItems[] # own line, not a total field
invoice_format -> xRechnung.buyerReference # profile comes back read-only
voucher_pdf -> files/ # max. 5 MBTwo fields in this mapping deserve particular attention. The first is the voucher number, and it serves as a counter-example: Lexware assigns it on creation and it is read-only (Lexware). The shop's order number therefore cannot be written into it; it belongs in a freely writable field such as title, introduction or remark, or in the contact assignment. Both number ranges then run side by side without one tearing gaps into the other; the integration only has to record which order number belongs to which voucher, as a field and not as a convention. The second is shipping cost. It is not a correction to the total but a line item with its own tax rate; deducting it at the totals field produces a voucher whose line items do not add up to its total. This coordination is the part of interface development that costs the most discussion and the least code.
- Define the trigger. Not every order is a voucher. The usual triggers are payment received or dispatch, not the click on the buy button. The trigger belongs in the documentation because it determines the revenue period.
- Assign the customer. If the contact already exists it is referenced, otherwise the address travels with the voucher. A new contact per order produces an unusable address base within months.
- Build the line items. Quantity, unit, net price and tax rate per row, shipping as its own row, discounts where they belong in business terms and not as a later correction to the total.
- Create the voucher and evaluate the response. The response carries the id of the voucher. It is stored on the order before anything else happens; without it the transaction cannot be found again on the next retry.
- Attach the document. The voucher PDF goes through the files endpoint and has a hard upper limit of 5 MB (Lexware); the documentation permits the formats PDF, JPG, PNG and XML.
The id is the anchor
Article master: an endpoint with clear edges
A dedicated endpoint for articles has not existed for very long. It was added on 11 July 2024 (Lexware). Integrations from before that time dragged master data along inside voucher line items, with all the consequences for reporting and maintenance. Anyone integrating today separates the two cleanly: the article master travels through the article endpoint, and the voucher refers to it. That is not a question of style; it decides whether a price change happens in one place or in a thousand.
Article number
Freely assignable and the natural key between shop and accounting. It should come from the leading system and stay there, one per article rather than one per channel. How to keep customer part numbers alongside it is a separate question.
GTIN
Unlike the article number it is validated: if a value is given, it has to match the formats GTIN-8, GTIN-12, GTIN-13 or GTIN-14 (Lexware). A free-text field carried over from the shop shows up here immediately.
Tax rate
On the article the permitted rates are 0, 7 and 19 (Lexware). Special cases such as intra-community supply, reverse charge or the small-business scheme are resolved at voucher level and not on the master record.
Price and currency
The price hangs on a currency, and the interface currently supports only EUR (Lexware). Several currencies in the shop therefore mean conversion before the transfer, with the rate recorded per voucher.
Unit
Unit of measure and pack size belong together before the first line item is created. How packs and units of measure are converted decides every later evaluation.
Synchronisation
A catalogue synchronisation reads across pages. The page size is 25 by default and can be raised to 100 or 250 depending on the endpoint (Lexware); for the article endpoint the table names the higher value.
The article synchronisation is the part most likely to run into the cap. A stock of 5,000 articles is read in 20 calls at a page size of 250, and in 200 calls at 25. Writing gets expensive faster, because every change is a call of its own: at two requests per second (Lexware) a full synchronisation of 5,000 articles takes more than 40 minutes if every record is touched. So not everything is written, only what changed, recognised by a fingerprint per record rather than by a timestamp that shifts during mirroring anyway.
- An article belongs to exactly one leading system. Maintained in both, it produces two truths and a recurring reconciliation effort; the pattern is familiar from master data synchronisation.
- Variant articles have a structure in the shop but a single number and price in accounting. The mapping is decided before the build, not after it.
- Deleted articles do not disappear retroactively from vouchers. The voucher carries the description as of the issue date; that is intended and has to be accounted for during synchronisation.
- A synchronisation without a marker starts from scratch every time. The marker belongs on your own side because the search window of the voucher list ends at 10,000 entries (Lexware).
Pace instead of bursts: cap, pages and conflicts
Alongside the cap of two requests per second (Lexware) the documentation also describes the behaviour of callbacks, and for day-to-day operation that matters at least as much. The configured read timeout is 5,000 ms, and triggering long-running processes synchronously inside the callback is explicitly not recommended (Lexware). So a callback accepts, writes to a queue and answers; the processing happens afterwards. Whether a callback or a paced poll is the right route depends on volume and on tolerance for delay. The trade-off between webhooks and polling usually falls in favour of the callback here, as long as the processing is decoupled.
If your own endpoint fails, the other side does not give up straight away. The first phase brings five retries after 10, 20, 40, 80 and 160 seconds (Lexware); according to the same page a pause of 30 minutes then follows, and a second phase with 20 retries at two-hour intervals. That is generous and precisely for that reason delicate, because a silent failure only becomes visible after many hours if nobody is watching. An integration without its own monitoring notices the outage at month end rather than in the morning. Robust error handling on interfaces is therefore part of the integration, not an afterthought.
09:00:00.0 GET /v1/articles?page=0&size=250 200 250 articles
09:00:00.5 GET /v1/articles?page=1&size=250 200 250 articles
09:00:00.7 GET /v1/articles?page=2&size=250 429 rejected
09:00:02.7 GET /v1/articles?page=2&size=250 200 retry after pause
...
09:16:40.0 POST /v1/invoices 201 id stored
09:16:41.0 PUT /v1/articles/47f1 409 conflict
09:16:42.0 GET /v1/articles/47f1 200 record re-read
09:16:43.0 PUT /v1/articles/47f1 200 writtenTwo status codes govern operation. One is the 429, which does not mean a queue but a refusal (Lexware). The other is the 409: if a record has meanwhile been changed by someone else, HTTP 409 Conflict comes back (Lexware). Concurrent writes are therefore not locked but rejected, and the integration resolves the conflict itself by re-reading, merging and writing again. Skip that, and every parallel edit from the user interface silently loses a change. Pacing, queueing and logging are exactly the tasks a middleware between shop and accounting is built for.
Two requests per second is a design parameter
E-invoicing: what decides the format
Whether a transferred invoice becomes an electronic invoice is not decided by a format field on the voucher. The field electronicDocumentProfile only reports which profile was produced: NONE, EN16931 as the hybrid format or XRechnung (Lexware); the documentation marks it as read-only (Lexware). The steering runs through the contact. If the customer's Leitweg-ID and your own vendor number at that customer are stored there, invoices conforming to the XRechnung standard are produced (Lexware); per invoice the Leitweg-ID can be overridden through the xRechnung object on the voucher (Lexware). This connects the integration to a legal development running in parallel. Since 2025 German law defines what an electronic invoice is: an invoice issued, transmitted and received in a structured electronic format that enables electronic processing (German VAT Act). A PDF attachment does not meet that; under the same provision it is an other invoice. Which recipient group needs which format belongs on the page about e-invoicing and not in the exception branch of the integration.
Smaller businesses get a transitional rule, but it hangs on a fixed threshold. Until 31 December 2027, invoices for turnover in 2027 may still be transmitted on paper or in a non-compliant electronic format if the total turnover of the issuing business in the preceding calendar year did not exceed 800,000 euros (German VAT Act). Anyone above that does not get the extension. And regardless of it, the issuing deadline runs: for supplies to other businesses the invoice has to be issued within six months of performing the supply (German VAT Act). An integration that collects vouchers and only transfers them at the end of a quarter works against that deadline.
| Value or standard | What sits behind it | What it matters for |
|---|---|---|
| NONE | no electronic invoice profile (Lexware) | vouchers not meant to count as e-invoices |
| EN16931 | hybrid format of PDF plus embedded data (Lexware) | recipients that process both parts |
| XRechnung | purely structured format (Lexware) | recipients that require this standard |
| Standard behind it | EN 16931, published on 28 June 2017 (Forum elektronische Rechnung Deutschland) | not a novelty, but a deadline |
| Format release | ZUGFeRD 2.5.2 (Forum elektronische Rechnung Deutschland) | moves faster than the integration |
| Current version | XRechnung 3.0, in force since 01.02.2024 (KoSIT) | the previous version expired on the same day |
It is worth looking beyond the national deadline. The Council of the European Union is rebuilding VAT in stages, and only the last of them falls in 2030: Article 5 of the directive amends the VAT Directive with effect from 1 July 2030 (Council of the European Union), while an earlier stage already takes effect on 1 July 2028 (Council of the European Union). The shorter invoicing deadline belongs to the 2030 stage: for cross-border transactions an invoice will in future be issued no later than ten days after the chargeable event occurs (Council of the European Union), where the fifteenth day of the following month applied before. The overhaul is justified with a revenue gap estimated at EUR 93 billion across the Union for 2020 (Council of the European Union). Anyone building a voucher route today builds it for that horizon and keeps the earlier stages in view; the details of the national implementation are in the article on the e-invoice mandate from 2027.
Retention: what happens after dispatch
A voucher is not done once it has been transferred. Accounting vouchers must be retained for eight years (German Fiscal Code), and VAT law repeats the same period independently for invoices: it starts at the end of the calendar year in which the invoice was issued (German VAT Act). In practice that means an invoice from January 2026 has to be available until the end of 2034, in a form that remains legible and machine-readable. That affects not only the accounting system but the integration itself: logs, assignments and the ids through which a shop transaction and a voucher find each other.
- Store the voucher id on the order and not only in a log. A log is rotated, an order stays.
- Keep the link between shop transaction, voucher and payment as a record and not as a report recalculated every time.
- Check attachments against the 5 MB limit before uploading (Lexware) and log the result of that check.
- Document number ranges and their gaps. What is self-explanatory today is a query during an audit in six years.
- Write the process description while you build; producing a process documentation afterwards costs a multiple.
- Model retention technically: eight years from the end of the calendar year (German VAT Act), retrievable without manual work.
And the voucher stream is rarely the only one produced from the same data. Anyone importing keeps reporting data with commodity code, country of origin and quantity alongside invoice and article; the CBAM deadline on 27 September shows how quickly a second data stream with its own deadline appears next to the books. Both draw on the same order and article data, and both get worse when they are maintained in different places.
How large the voucher stream really is
Online retail in Germany is not a niche channel. It last grew by 3.9 percent to 92.3 billion euros net (HDE), and the online share of total retail stands at 13.5 percent (HDE). Every one of those transactions produces at least one voucher that has to reach the books. On the supply side the share is similarly tangible: in the Web Almanac 2025 data set, 19.9 percent of all desktop pages examined were identified as shops (Web Almanac). Voucher and article synchronisation is therefore not a special case but a standard problem with a known shape of solution.
What is striking is how small the businesses often are. In the European Union 23.59 percent of enterprises had electronic sales (Eurostat); among small enterprises with 10 to 49 employees the figure is 21.38 percent, generating 8.65 percent of their turnover that way (Eurostat). And those that do sell electronically overwhelmingly use their own website: 91.19 percent of small enterprises with electronic sales use the web for it, and 17.52 percent use the exchange of structured messages (Eurostat). At exactly this scale, automation only pays off if it runs without daily supervision.
The German picture fits that. Slightly more than half of enterprises with ten or more employees use paid cloud services, namely 54 percent in 2025 (Federal Statistical Office). Inventory management and customer management, however, are comparatively rare among them, at 23 percent of cloud-using enterprises each (Federal Statistical Office). An integration therefore often connects accounting in the cloud with an inventory system that sits on the company's own premises. How that bridge is built without the two sides slowing each other down is the central question of every ERP and inventory integration.
What should be settled before the first call
Most integrations do not fail on a field but on a question nobody asked. That is why a short list of decisions comes before the first call. Each of them costs minutes to clarify and days to rebuild. We work through this list once in full during a preliminary discussion about the Lexware integration, before a single line of code exists.
- Define the trigger for the voucher: order, payment received or dispatch. That decides the revenue period.
- Name the leading system per data type: articles, prices, customers, vouchers. Exactly one for each type.
- Keep number ranges separate and hold the assignment in a field, not as a convention in someone's head.
- Carry the limits into the architecture: two requests per second, at most 300 line items per voucher, 5 MB per attachment (Lexware).
- Decide on retry and transaction key before the first 429 appears in the log (Lexware).
- Provide for conflict handling: a 409 is not an error but an instruction to re-read and write again (Lexware).
- Decide the invoice format per recipient group and store it on the contact, that is Leitweg-ID and vendor number at the customer (Lexware); the field electronicDocumentProfile only reports the produced profile back (Lexware).
- Plan monitoring that reports a silent outage before the monthly closing, plus a fallback mode for the case where the other side stays quiet for longer.
An integration is only as good as its behaviour in the exceptional case. Normal operation is in the documentation; what happens on a 429, on a 409 and on a silent callback decides whether somebody has to rework things at month end.
Sources and studies