App guides
The Lexware Office app creates invoices and credit notes in Lexware Office, formerly lexoffice, for your Swell orders. When an order is paid, the app creates its invoice in Lexware. When a payment of the order is refunded, it creates a credit note that names the invoice. Titles, introduction and closing texts, the layout and the number ranges come from your Lexware settings.
Each invoice's total is the order's total to the cent, with the Lexware tax type that matches the tax Swell charged. Documents are created as drafts to review in Lexware, or finalized with a PDF. Each one is listed on its order in Swell with its number, its status in Lexware, the PDF and a link into Lexware.
| When | What the app does |
| An order is paid | Creates its invoice in Lexware, if Create documents automatically is on. Orders in other currencies than EUR are skipped. |
| A payment of an invoiced order is refunded | Creates a credit note for the refunded amount that names the invoice, if Create credit notes for refunds is on. |
| A document is finalized in Lexware | Saves its number and PDF on the document in Swell, and e-mails the customer a link to the PDF if E-mail documents to customers is on. For a draft you finalize in Lexware, this happens when you read it again. |
| Lexware refuses a document, or no invoice can be built for the order | Lists the document under Needs attention with the reason, and e-mails the store's administrators. |
| You choose Create Lexware invoice on an order, or Create Lexware invoices on selected orders | Creates the invoice now, whether or not the order is paid. |
| You choose Retry, or Retry failed documents | Tries again, without creating a document that's already in Lexware a second time. |
- A Lexware Office account on a plan with the Public API, which the app's settings name as the XL plan.
- Your company data and tax settings complete in Lexware. The app reads whether you're a small business (§19 UStG) or tax-exempt, and whether you charge EU consumers their own country's VAT, and chooses each invoice's tax type from them. Tax-free invoices to businesses in other EU countries also need your own VAT ID in Lexware.
- Orders in EUR. Lexware Office issues invoices in EUR only, so orders in other currencies are skipped.
- Swell taxes that match what you owe. The app doesn't calculate tax. It uses the tax Swell charged, so orders to German and EU consumers need tax charged, and tax has to be calculated after discounts. In Settings > Taxes, under Show advanced options, turn on Apply taxes after discounts.
- For tax-free sales to businesses in other EU countries, the customer's VAT ID on the order's billing address or on the customer account.
Install Lexware Office from the Swell App Store, and set it up in your test environment before the live one.
Create an API key
In Lexware, go to Extensions > Public API (app.lexware.de/addons/public-api) and create an API key with all permissions. Copy the key. Lexware shows it in full only when it's created.
Connect Lexware
In Swell, go to Apps > Lexware Office > Settings, paste the key into API key and click Save settings. Then click Test connection. The message names your Lexware company and how it's set up, for example regular VAT, EU consumers are invoiced with German VAT, and Connected account shows the company name.
Choose how documents are created
Under Documents, keep Create documents as set to Drafts, to review and finalize in Lexware while you test. Choose the Document language, and whether to create credit notes for refunds and e-mail documents to customers. Click Save settings.
Turn on automatic documents
Under Connection, turn on Create documents automatically and click Save settings. From then on, paid orders and refunds get their documents. Orders paid before this aren't invoiced automatically.
Place a test order
Place and pay a test order in EUR. Open the order's Lexware tab: it lists the invoice with the status In Lexware and Status in Lexware draft, and the draft is in Lexware. Check the lines, the tax and the total there. To test a credit note, refund part of the payment in Swell.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 to 4, and choose drafts or finalized documents for your live orders.
Test orders create real documents in the Lexware account the API key belongs to, and a finalized document can't be changed or deleted through the app, only corrected in Lexware. Use a separate Lexware account for the test environment, or keep it on drafts and delete the test drafts in Lexware. To stop test orders creating documents, turn off Create documents automatically in the test environment.
To invoice orders placed before you installed the app, select them in the order list and choose Create Lexware invoices.
When an order is paid and Create documents automatically is on, the app creates its invoice in Lexware. The invoice is addressed to the order's billing address, or to the shipping address when the billing address has none, and has:
- A first line that names the order and its date, such as Bestellung Nr. 1042 vom 10.10.2026.
- One line per item, with the product and variant name or its options, the quantity and the price before discounts.
- One line for shipping, named after the shipping service.
- Discounts as a negative line per tax rate, named after the coupon code if there is one.
- For a paid order, a payment term that says the amount was already paid, and how, such as Der Rechnungsbetrag wurde bereits per Kreditkarte beglichen.
The invoice is dated the day it's created, in German time, and its delivery date is the order's date. Its total is the order's total to the cent. Lexware rounds each line and calculates tax per tax rate, while Swell calculates tax per item, so the app repeats Lexware's calculation before it sends anything. When store prices exclude tax, the invoice has net prices if that gives the order's total, and gross prices otherwise. When store prices include tax, it has gross prices. An order whose amounts can't give its total, or whose tax isn't what its tax rates give, isn't sent and is listed under Needs attention.
For an invoice to an address outside Germany, or an order taxed as a sale to another country, Lexware needs a customer contact. The app creates one, as a company when the address has a company name or the customer a VAT ID, and uses it again for the same customer's later orders.
The app doesn't record payments in Lexware. Invoices of paid orders arrive with a payment term of 0 days, and you assign the payment in Lexware as usual.
When a payment is refunded, and Create documents automatically and Create credit notes for refunds are on, the app creates a credit note for the refunded amount if the order has a Lexware invoice. Each refund gets its own credit note. Its first line names the invoice, the order and the refund, such as Erstattung zu Rechnung RE0042, Bestellung Nr. 1042 (Ref. 100019).
- A refund of the whole invoice repeats the invoice's lines.
- A partial refund becomes one line per tax rate, split in the proportion the rates have on the invoice, and adds up to the refunded amount exactly.
- Refunds that would add up to more than the invoice aren't sent.
- The credit note uses the invoice's language and tax type, and isn't linked to the invoice in Lexware. It names the invoice in its first line.
Refunds of orders the app didn't invoice, or whose invoice was skipped, are ignored. If the order's invoice needs attention, the credit note is listed under Needs attention. Retry it once the invoice is in Lexware. There's no action to create a credit note for a refund made while automatic documents or credit notes were off. Create it in Lexware instead.
The app chooses the Lexware tax type that matches the tax Swell charged. The country is the shipping country for orders with items to ship, and the billing country for other orders.
| Order | Lexware tax type |
| Your Lexware account is a small business (§19 UStG) or tax-exempt | Without VAT. An order that was charged tax needs attention. |
| Germany | Net or gross, with the tax charged. |
| Another EU country, tax charged | Net or gross, with the tax charged. When Lexware is set to charge EU consumers their own country's VAT, marked as a distance sale, or as an electronic service when nothing is shipped. |
| Another EU country, no tax, customer has a VAT ID | Intra-community supply, tax-free. |
| Outside the EU, tax charged | Net or gross, with the tax charged. |
| Outside the EU, no tax | Export of goods when items are shipped, or service to a third country when nothing is shipped, tax-free. |
An order to Germany or another EU country that was charged no tax, without a VAT ID, needs attention, unless it has only gift cards or free items. So does an order with tax rates that Lexware doesn't accept for the country, for example your destination country's rate while Lexware is set to charge German VAT to EU consumers. The document's Lexware tax type shows the type the app chose, such as gross or net / distanceSales.
Create documents as decides how new documents are created:
- Drafts, to review and finalize in Lexware creates drafts, which you can edit, finalize or delete in Lexware. A draft has no PDF, so it isn't e-mailed. New installs create drafts.
- Finalized documents creates documents that are numbered, booked and have a PDF at once. They can't be changed or deleted afterwards, only corrected in Lexware.
The app doesn't check Lexware for drafts you finalize there. After you finalize one, open the document in Swell and choose Read again from Lexware. The app reads its number and status, saves the PDF and e-mails the customer if that's on. To read several at once, select them on the Drafts tab of Orders > Lexware documents and choose Retry.
If a draft was deleted in Lexware, reading it again lists it under Needs attention. Choose Retry to create it again, or Mark as resolved to leave it.
With E-mail documents to customers on, each finalized invoice and credit note is e-mailed to the customer once, with a link to the PDF. The e-mail is sent to the e-mail address of the order's customer account, in the document's language. Drafts are sent once you finalize them in Lexware and read them again. Documents without a customer e-mail aren't sent.
The e-mail is the notification Lexware document for the customer, which you can edit or turn off under Settings > Notifications. E-mailed to customer on the document shows whether it was sent. The PDF is stored as a file in Swell, and anyone with the link can open it.
To invoice an order that the automation doesn't cover, such as an unpaid bank transfer order or an order from before you installed the app, open the order and choose Actions > Create Lexware invoice, then Create invoice. To invoice several, select them in the order list and choose Create Lexware invoices. These work whether or not Create documents automatically is on.
Orders that already have an invoice are left alone, and orders in other currencies than EUR are skipped. An unpaid order's invoice doesn't say it's paid, and gets Lexware's default payment terms.
Orders > Lexware documents lists every invoice and credit note the app created or tried to create, with the number, type, order, customer, total, status and problem. Its tabs:
- Needs attention: documents the app couldn't create, with the reason.
- In Lexware: documents that are in Lexware, drafts included.
- Drafts: documents that were drafts when the app last read them.
- Skipped: orders the app doesn't invoice, such as orders in other currencies than EUR.
A document's page shows its number, status, total, problem, order and customer, the PDF, its status in Lexware, the document date, the tax type, the invoice a credit note belongs to, and whether the customer was e-mailed. View in Lexware opens it in Lexware. Each order's Lexware tab lists its documents.
If Lexware can't be reached, is busy or doesn't answer in time, Swell sends the order or refund to the app again later. After a day of failed attempts, the document is listed under Needs attention with Lexware could not be reached for a day.
Correct the cause first, for example the API key or your tax settings. Then:
- To retry one document, open it and choose Retry.
- To retry several, select them under Orders > Lexware documents and choose Retry.
- To retry every document under Needs attention, and finish the ones that were interrupted, choose Actions > Retry failed documents in the app settings.
A document that's already in Lexware is never created twice. If Lexware created it but its answer was lost, the app finds it in Lexware by its time, total and first line before it creates anything. A retry of a document that's in Lexware only reads its number, status and PDF.
Retrying several documents and Create Lexware invoices run in the background, five documents at a time. The action shows Running while they work, and a message when they finish. The runs are listed under Apps > Lexware Office > Workflows. If Lexware refuses the API key or the plan, the run stops at the first document.
To stop the app from creating a document, for example after you created it in Lexware by hand or decided none is needed, open it and choose Mark as resolved. Optionally enter the Document number in Lexware (optional), then click Mark as resolved. The document's status becomes Resolved by hand.
When the order's invoice was resolved by hand, the app can't build credit notes from it, so its refunds need attention and their credit notes have to be created in Lexware by hand too. A document that's in Lexware but couldn't be read is marked as In Lexware and left as it is.
When documents need attention, or Lexware refuses the connection, the app e-mails the store's administrators with the problem and a link to the app. The subject starts with Action needed:. You get one e-mail per problem, not one per order: while the same kind of problem keeps coming back within a day, no new e-mail is sent. A new one is sent after the problem was cleared, or after a day without it.
The e-mail is the notification Lexware Office needs attention, which you can edit or turn off under Settings > Notifications.
| Where | What it's for |
| Apps > Lexware Office > Settings | The API key, Test connection, the Create documents automatically switch and the document settings. |
| Apps > Lexware Office > Settings, Actions menu | Retry failed documents. |
| Apps > Lexware Office > Workflows | The background runs of Retry failed documents, Retry and Create Lexware invoices. |
| Orders > Lexware documents | Every invoice and credit note, with the Needs attention, In Lexware, Drafts and Skipped tabs, and Retry for selected documents. |
| A document | Its number, status, PDF and problem, View in Lexware, and Retry, Read again from Lexware and Mark as resolved. |
| An order's Lexware tab | The order's invoice and credit notes. |
| An order's Actions menu | Create Lexware invoice. |
| The order list, with orders selected | Create Lexware invoices. |
| Settings > Notifications | The e-mails Lexware document for the customer and Lexware Office needs attention. |
Settings are in Apps > Lexware Office > Settings and are saved separately for each environment. They're in two sections, Connection and Documents.
| Setting | Description | Default |
| API key | Connection. From Extensions > Public API in Lexware. Masked on the settings page. | None |
| Connected account | Connection. Read-only. The Lexware company the key belongs to, filled in by Test connection. | Not tested yet |
| Create documents automatically | Connection. While on, an invoice is created when an order is paid, and a credit note when a payment of an invoiced order is refunded. Orders in other currencies than EUR are skipped. The actions on orders and documents work either way. | Off |
| Create documents as | Documents. Drafts, to review and finalize in Lexware, or Finalized documents. A finalized document is numbered, booked and has a PDF at once, and can't be changed or deleted afterwards. | Drafts, to review and finalize in Lexware |
| Document language | Documents. German, English, or German for Germany, Austria, Switzerland and Liechtenstein, English elsewhere, by the billing country. Sets the invoice's language in Lexware, the lines the app adds and the customer e-mail. Credit notes use their invoice's language. | German |
| Create credit notes for refunds | Documents. Each refund of an order that has a Lexware invoice becomes a credit note that names the invoice. | On |
| E-mail documents to customers | Documents. E-mails each finalized invoice and credit note to the customer, with a link to the PDF. Drafts aren't sent until they're finalized and read again. | Off |
- Only orders in EUR are invoiced.
- Invoices aren't marked as paid in Lexware. Assign the payments there.
- Changes to an order after its invoice, such as edited or canceled items without a refund, aren't sent to Lexware. Canceling an order doesn't cancel its invoice.
- Credit notes are for an amount, not for items, because a Swell refund names no items. They're created only automatically, for refunds of orders with a Lexware invoice.
- The app doesn't follow drafts in Lexware. Read a draft again after you finalize it there.
- Only orders are invoiced. Subscription charges that don't create an order aren't.
- The app doesn't calculate tax. Orders whose tax doesn't fit a Lexware tax type, or doesn't match their tax rates, are listed under Needs attention and have to be invoiced by hand.
- Customers get a link to the PDF, not an attachment. Anyone with the link can open the PDF.
- The app sends Lexware at most two requests a second, so bulk actions on many orders take a while.
- Each environment uses the Lexware account of its API key. Test orders create real documents there.
Problems with a document are shown in Problem on the document, and under Orders > Lexware documents > Needs attention. The app also logs them. In the Swell dashboard, the logs are under Developer > Console > Logs.
Lexware did not accept the API key means the key is wrong, deleted or expired. Copy it again from Extensions > Public API in Lexware, or create a new one, then save and test again. The Lexware account has no active plan with API access means your Lexware plan doesn't include the Public API. Enter the API key, save the settings, then test again means no key is saved.
Check that Create documents automatically is on and saved, and that the order is in EUR. Orders paid before it was turned on, and orders that never become paid, such as unpaid bank transfer orders or free orders without a payment, aren't invoiced automatically. Choose Actions > Create Lexware invoice on the order. If the order is listed under Needs attention or Skipped, Problem says why.
The key lacks a permission. Create a key with all permissions in Lexware, enter it in the app settings, click Test connection, then choose Actions > Retry failed documents.
The order goes to Germany or another EU country and was charged no tax, but has no VAT ID and isn't only gift cards or free items. Check the store's tax rules. If no tax is correct, create the invoice in Lexware by hand and mark the document as resolved. For a business customer in another EU country, add their VAT ID to the order's billing address or customer account, then retry.
Your Lexware account is a small business or tax-exempt, but the store charges tax. Correct the tax settings in Swell or in Lexware, then retry. Orders that were charged tax have to be invoiced by hand.
Lexware doesn't accept those rates for that country. Check the store's tax rules, and for EU consumers whether Lexware is set to charge their own country's VAT. The tax rates the store charges and the Lexware setting have to agree. Then retry.
Enter your VAT ID in Lexware's company data, then retry.
Usually the store calculates tax before discounts. In Settings > Taxes, under Show advanced options, turn on Apply taxes after discounts for future orders. Create this invoice in Lexware by hand and mark the document as resolved.
No invoice with exactly the order's total can be built from its amounts. Create the invoice in Lexware by hand and mark the document as resolved.
Add the name or country to the order's address, then retry.
A refund's credit note waits for its invoice. Correct the invoice's problem and retry it, then retry the credit note.
The order's refunds add up to more than its invoice, for example after the order total was changed. Create this credit note in Lexware by hand and mark it as resolved.
A draft was deleted in Lexware, or the API key now belongs to another Lexware account. Choose Retry to create the document again, or Mark as resolved to leave it. A credit note for an invoice that's gone has to be created in Lexware by hand.
Lexware was down or busy for a day, so the app stopped trying. Choose Retry on the document, or Actions > Retry failed documents in the app settings.
Drafts have no PDF. Finalize the draft in Lexware, then open the document in Swell and choose Read again from Lexware.
Check that E-mail documents to customers is on, that the document is finalized and has a PDF, and that the order's customer has an e-mail address. Check that the notification Lexware document for the customer is on under Settings > Notifications. Documents created before you turned e-mails on are sent when you retry them.
Uninstalling the app stops creating invoices and credit notes, and removes the app's settings page, the Lexware documents list, the order's Lexware tab and actions, and the two notifications. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.
The records under Lexware documents are kept and come back if you reinstall, so documents already in Lexware aren't created again. Invoices, credit notes and contacts in Lexware stay there. The app isn't notified when it's uninstalled, so if you no longer need the API key, delete it in Lexware under Extensions > Public API.
| Function | Runs on | What it does |
| invoice-order | order.paid, while Create documents automatically is on | Creates the order's document record, then the invoice in Lexware. |
| credit-refund | payment.refund.succeeded, while Create documents automatically is on | Creates the credit note for a refund of an invoiced order, when credit notes are on. |
| create-invoice | The Create Lexware invoice action on an order | Creates the order's invoice, or reports the one it has. |
| process-document | The Retry and Read again from Lexware actions on a document | Works on one document record until it's complete or needs attention. |
| resolve-document | The Mark as resolved action | Sets the record to resolved, or to created when the document is in Lexware. |
| test-connection | The Test connection button | Reads the Lexware profile, saves the company name and clears the connection alert. |
| process-documents | A workflow, run by Retry failed documents, Retry on selected documents and Create Lexware invoices on selected orders | Works through the documents or orders five per step, in id order. |
Each invoice and credit note has a record in the app collection apps/lexware/documents, written before anything is sent to Lexware. Its key, invoice:<order id> or credit_note:<refund id>, is unique, so each order gets one invoice and each refund one credit note. Other fields: type, status (pending, created, failed, skipped or resolved), source, name, number, invoice_number, order_id, order_number, account_id, payment_id, refund_id, reference, customer_name, customer_email, language, amount, currency, tax_type, lexware_id, lexware_status, lexware_url, contact_id, contact_key, pdf, problem, problem_code, attempts, date_attempted, date_submitted, date_issued, locked_until and notify_customer.
Open problems are records in apps/lexware/alerts, one per key (connection or documents), with message, subject, count, date_last_seen and app_id. Creating one sends the admin notification. Setting notify_customer to true on a document fires its ready event, which sends the customer notification.
Orders get a documents link field under $app.lexware, which lists the order's records in apps/lexware/documents. Nothing is stored on the order.
The app calls the Lexware Office API at https://api.lexware.io/v1 with the API key as a Bearer token: GET /profile, POST /invoices and POST /credit-notes (with finalize=true for finalized documents), GET and GET .../file for each document, POST /contacts and GET /voucherlist. Calls are spaced 500 ms apart, wait and repeat twice on 429, and time out after 7 seconds.
A worker takes a record by raising attempts with $inc and holding locked_until for 30 seconds, so of two attempts only one goes on. date_submitted is set before the create call and cleared when Lexware answers. A record still marked on a later attempt is looked up in Lexware's voucher list, among documents created around the mark, by total and by the order number or refund reference in the first line. For a Lexware 429, 5xx or network error, the event functions throw a 503 SwellError so Swell delivers the event again, until a day after the first failed delivery. The PDF is saved to the pdf file field as $base64 data.
Swell builds and maintains the Lexware Office app. For help with the app, email support@swell.is. For questions about your Lexware Office account, contact Lexware.