# Lexware Office Source: https://developers.swell.is/app-guides/lexware 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. ## How it works | 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. | ## Before you begin - 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. ## Set up Install Lexware Office from the Swell App Store, and set it up in your test environment before the live one. **1. 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. **2. 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. **3. 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**. **4. 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. **5. 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. **6. 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**. ## Using Lexware Office ### 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. ### Credit notes 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. ### Tax types 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`. ### Drafts and finalized documents **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. ### E-mailing documents to customers 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. ### Creating invoices by hand 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. ### Lexware documents **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. ### Retrying 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. ### Marking as resolved 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. ### E-mails to administrators 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**. ### In the dashboard | 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 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 | ## Limitations - 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. ## Troubleshooting 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**. ### Test connection fails `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. ### Paid orders get no invoice 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 API key is not allowed to do this" 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 was charged no tax, and nothing shows why" 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. ### "The order was charged tax, but the Lexware account is set up to issue invoices without VAT" 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. ### "The order's tax rates (…) are not valid in Lexware for a customer in …" 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. ### "Lexware needs your company's own VAT ID for a tax-free invoice to another country" Enter your VAT ID in Lexware's company data, then retry. ### "The tax charged on the order (…) is not what its tax rates give (…)" 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. ### "The order's items, shipping, discounts and tax do not add up to its total of …" 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. ### "The order has no name in its billing address" or "The order has no country in its billing or shipping address" Add the name or country to the order's address, then retry. ### "The invoice for this order has not been created in Lexware yet" A refund's credit note waits for its invoice. Correct the invoice's problem and retry it, then retry the credit note. ### "Refunds of … EUR are more than invoice …" 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. ### "… no longer exists in the connected Lexware account" 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 could not be reached for a day" 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. ### A draft has no PDF and wasn't e-mailed Drafts have no PDF. Finalize the draft in Lexware, then open the document in Swell and choose **Read again from Lexware**. ### Customers don't get the e-mail 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 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**. ## For developers | 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:` or `credit_note:`, 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. ## Support 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.