App guides
The sevdesk app creates invoices and credit notes in sevdesk for your Swell orders, and books their payments. When an order is paid, the app creates its invoice in sevdesk. Once the invoice is finalized, each payment is booked on the sevdesk account you name, so the invoice is marked as paid. When a payment is refunded, the app creates a credit note for the invoice and books the payout. The layout, letterhead and number ranges come from your sevdesk account.
Each invoice's total is the order's total to the cent, with the sevdesk tax rule that matches the tax Swell charged. Documents are created as drafts to review in sevdesk, or finalized with their number, payment booking and PDF at once. Each one is listed on its order in Swell, and its page has the number, the status in sevdesk, the PDF and a link into sevdesk.
| When | What the app does |
| An order is paid | Creates its invoice in sevdesk, if Create documents automatically for paid orders and refunds 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 refers to the invoice, if Create credit notes for refunds is on too. |
| A document is finalized | Saves its number, books its payments or payout on the accounts set under Payments, stores the PDF on the document in Swell, and e-mails the customer a link to the PDF if that's on. For a draft you finalize in sevdesk, this happens when you read it again. |
| An order is paid after its invoice was created | Books the payment on the invoice, if automatic documents are on. |
| sevdesk 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. |
| sevdesk can't be reached | Tries again for about ten minutes, then every half hour. After a day, lists the document under Needs attention. |
| You choose Create sevdesk invoice on an order, or Create sevdesk 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 sevdesk a second time. |
- A sevdesk account on sevdesk-Update 2.0, sevdesk's current bookkeeping system. Test connection says so if your account is on the older system, which sevdesk offers to update under Einstellungen > System.
- Your company data and tax settings complete in sevdesk. The app reads whether your account is a small business (§ 19 UStG) that invoices without VAT, and the payment term you set for invoices.
- A clearing account (Verrechnungskonto) for your shop in sevdesk, added under Bank > Verrechnungskonto. sevdesk takes payment bookings from the app only on an account without a bank behind it. Without one, nothing is booked and invoices stay open in sevdesk.
- The API token of your sevdesk user, from Einstellungen > Benutzer in sevdesk.
- Orders in EUR. The app creates sevdesk documents 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 sevdesk from the Swell App Store, and set it up in your test environment before the live one.
Prepare sevdesk
In sevdesk, complete your company and tax settings. Under Bank > Verrechnungskonto, add a clearing account for your shop, for example Online-Shop. Then open Einstellungen > Benutzer, choose your user and copy the API token.
Connect sevdesk
In Swell, go to Apps > sevdesk > Settings, paste the token into API token and click Save settings. Then click Test connection. The message names your sevdesk account and says whether it invoices with regular VAT or as a small business, and Connected account shows the account's name.
Set up payment booking
Under Payments, enter the clearing account's name in sevdesk account for shop payments, as it's written in sevdesk. For each payment method whose money doesn't arrive on that account, add a row under Payment method exceptions with the method's ID in Swell, such as paypal or the ID of a manual method, and another sevdesk account, or no account to book nothing for it. Click Save settings.
Click Test connection again. The message lists the sevdesk accounts that take bookings, and says Payments are booked on "Online-Shop". when the names match.
Choose how documents are created
Under Documents, keep Create documents as set to Drafts, to review and finalize while you test. Choose the Document language and how Sales to other EU countries are booked, and whether to create credit notes for refunds and e-mail finalized documents to customers. Click Save settings.
Turn on automatic documents
Under Connection, turn on Create documents automatically for paid orders and refunds and click Save settings. From then on, paid orders and refunds get their documents. Orders paid before this aren't invoiced automatically.
Test with an order
Place and pay a test order in EUR. Open the order's sevdesk tab: it lists the invoice with the status In sevdesk and Status in sevdesk set to Draft. Open the document and choose View in sevdesk to check the lines, the tax and the total there.
To test the rest, choose Actions > Finalize draft on the document, then Finalize. The invoice gets its number, Payment booking says what was booked, such as Paid in sevdesk., and the PDF is stored on the document. To test a credit note, refund part of the payment in Swell after the invoice is finalized.
Go live
Settings are saved separately for each environment. In the live environment, repeat steps 2 to 5, and choose drafts or finalized documents for your live orders.
The app has no test mode. Test orders create real documents, bookings and contacts in the sevdesk account the API token belongs to, and a finalized document takes a number from your number range and can't be changed or deleted afterwards. Use a separate sevdesk account for the test environment, or keep it on drafts and delete the test drafts in sevdesk.
To invoice orders placed before you installed the app, select them in the order list and choose Create sevdesk invoices.
When an order is paid and Create documents automatically for paid orders and refunds is on, the app creates its invoice in sevdesk. The invoice is addressed to the order's billing address, or to the shipping address when the billing address has none, and has:
- An introduction that names the order and its date, such as Bestellung Nr. 1042 vom 10.10.2026. The order number is also in sevdesk's reference field.
- 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, such as Versand (DHL Paket).
- Discounts as a negative line per tax rate, named after the coupon code if there is one, such as Rabatt (SUMMER10).
- For a paid order, a closing text 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, and its delivery date is the order's date. Its payment term is the one set for invoices in your sevdesk account. It gets its number from your sevdesk number range when it's finalized. Until then, it's named Invoice for order 1042 in Swell.
The invoice's total is the order's total to the cent. sevdesk calculates every total itself, line by line, while Swell calculates tax per item and rounds only the order total, so the app repeats sevdesk'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. The app then compares sevdesk's own total on the draft with the order. If a net draft is a cent off, the app replaces it with the same lines as gross prices. If the total still differs, the draft is deleted before it gets a number, and the document is listed under Needs attention.
Every sevdesk document needs a contact. The app uses the sevdesk contact that has the customer's e-mail address, or the one it used for the same customer before, or creates one with the address and e-mail address. A new contact is a company when the address has a company name. For a tax-free sale to a business in another EU country, the app uses only a contact with the customer's VAT ID, and creates one if needed. Existing contacts aren't changed.
When a document is finalized, the app books its payments in sevdesk, so the invoice arrives as paid and the credit note as paid out. sevdesk takes these bookings only on an account without a bank behind it, such as a clearing account.
- Each successful payment of the order is booked on sevdesk account for shop payments, with its own amount and date, up to the invoice total.
- A payment method with a row under Payment method exceptions is booked on that row's account, or not at all when the row has no account. No account is right for bank transfers, and for a PayPal account that's connected to sevdesk, where sevdesk matches the imported transactions itself.
- Gift cards (giftcard) and store credit (account) are booked only when they have a row with an account.
- A refund's payout is booked on the account of the refund's payment method, by the same rules.
- With no account entered anywhere, nothing is booked and invoices stay open in sevdesk.
The document's Payment booking says what was done, such as Paid in sevdesk., 40.00 of 108.94 EUR booked in sevdesk. or Not booked: 68.94 EUR paid by paypal, which has no sevdesk account in the app's settings. An invoice whose payments aren't all booked stays open or partly paid in sevdesk, and you assign the rest there.
When an order is paid after its invoice was created, for example an invoice you created on demand, the app books the payment on the invoice. Payouts from your payment provider to your bank, and its fees, aren't booked by the app.
If the account's name isn't found in sevdesk, or names an account that's connected to a bank, the document is still finalized and has its PDF, and it's listed under Needs attention. Correct the name and choose Retry to book the payment.
Status in sevdesk shows Draft, Open, Partly paid or Paid as it was when the app last read the document. Payments you assign in sevdesk later aren't shown in Swell.
When a payment is refunded, and Create documents automatically for paid orders and refunds and Create credit notes for refunds are on, the app creates a credit note for the refunded amount if the order has a sevdesk invoice. Each refund gets its own credit note, which refers to the invoice in sevdesk. It's titled Rechnungskorrektur zur Rechnung Nr. RE-1042, and its introduction names the order and the refund, such as Erstattung zur 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 of what the invoice still holds at each rate after its earlier credit notes, and adds up to the refunded amount exactly.
- Refunds that would add up to more than the invoice aren't sent.
- The credit note has the invoice's tax rule, address and language, and is a draft or finalized as Create documents as says.
sevdesk takes a credit note only for a finalized invoice. While the invoice is a draft, the credit note is listed under Needs attention. Finalize the invoice, then retry the credit note. The same applies when the invoice itself needs attention: retry the credit note once the invoice is in sevdesk.
Refunds of orders the app didn't invoice, or whose invoice was skipped, are ignored. There's no action to create a credit note for a refund made while automatic documents or credit notes were off. Create it in sevdesk instead.
The app chooses the sevdesk tax rule 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. The document's sevdesk tax rule shows the rule's name in English.
| Order | sevdesk tax rule |
| Your sevdesk account is a small business (§ 19 UStG) | No VAT, § 19 UStG. An order that was charged tax needs attention. |
| Germany, tax charged | Taxable revenue. |
| Germany or another EU country, no tax, only gift cards or free items | Taxable revenue, at 0 %. |
| Another EU country, tax charged at German rates, with Sales to other EU countries set to By the tax rate charged | Taxable revenue. |
| Another EU country, tax charged at other rates, or at any rate with Always under the One-Stop-Shop | One-Stop-Shop, goods when items are shipped, or One-Stop-Shop, electronic services when nothing is shipped. |
| Another EU country, no tax, customer has a VAT ID | Intra-community supply when items are shipped, or Reverse charge, EU when nothing is shipped. |
| Outside the EU, tax charged at German rates | Taxable revenue. |
| Outside the EU, no tax | Export when items are shipped, or Not taxable in Germany when nothing is shipped. |
With By the tax rate charged, a taxed sale to another EU country at German rates (19, 7 or 0 %) is booked as German revenue, and any other rate under the One-Stop-Shop. If you're registered for the One-Stop-Shop, choose Always under the One-Stop-Shop, so that a country whose rate equals a German one is booked correctly too.
Orders that fit no rule aren't sent and are listed under Needs attention: an order to Germany or another EU country that was charged no tax without a VAT ID, an order that was charged tax while your sevdesk account is a small business, an order outside the EU taxed at a rate that isn't German, and an order to another country with both shipped items and items that aren't shipped, such as downloads, unless it's booked as taxable revenue. sevdesk allows one tax rule per document. Gift cards and free items don't count as items that aren't shipped. sevdesk also checks the rates against the rule and refuses, for example, 16 % in Germany.
Every document starts as a draft in sevdesk. Create documents as decides what happens next:
- Drafts, to review and finalize stops at the draft. A draft has no number, and you can edit or delete it in sevdesk. Its payments aren't booked, it has no PDF in Swell and it isn't e-mailed until it's finalized. New installs create drafts.
- Finalized documents finalizes each document at once: it gets its number, its payments are booked and its PDF is stored. It can't be changed or deleted afterwards, only corrected.
To finalize a draft from Swell, open the document and choose Actions > Finalize draft, then Finalize. To finalize several, select them on the Drafts tab of Orders > sevdesk documents and choose Finalize drafts. Documents that aren't drafts are left as they are.
The app doesn't check sevdesk for drafts you finalize there. After you finalize one in sevdesk, open the document in Swell and choose Actions > Read again from sevdesk. The app reads its number, books the payments, stores the PDF and e-mails the customer if that's on. To read several at once, select them on the Drafts tab and choose Retry.
If a draft was deleted in sevdesk, reading it again lists it under Needs attention. Choose Retry to create it again, or Mark as resolved to leave it.
With E-mail finalized documents to customers, with a link to the PDF on, each finalized invoice and credit note is e-mailed to the customer once, with a link to the PDF. The e-mail goes to the e-mail address of the order's customer, in the document's language: German, with the subject Ihre Rechnung or Ihre Rechnungskorrektur, or English, with Your invoice or Your credit note, followed by the number and the store's name. Drafts are sent once they're finalized in Swell, or finalized in sevdesk and read again. Documents without a customer e-mail address aren't sent.
The e-mail is the notification sevdesk 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 sevdesk invoice, then Create invoice. To invoice several, select them in the order list and choose Create sevdesk invoices, then Create invoices. These work whether or not automatic documents are on, and create drafts or finalized documents as Create documents as says.
An order that already has an invoice gets no second one. If a payment came after its invoice, the action books it. Orders in other currencies than EUR are skipped. An unpaid order's invoice doesn't say it's paid. When the order is paid later while automatic documents are on, the payment is booked on its invoice. If they were off, choose Create sevdesk invoice on the order again to book it.
Documents the app couldn't create or finish are listed under Orders > sevdesk documents > Needs attention, with the reason in Problem. Correct the cause first, for example the API token, the payment account's name or your tax settings. Then:
- To retry one document, open it and choose Actions > Retry.
- To retry several, select them under Orders > sevdesk documents and choose Retry.
- To retry every document under Needs attention, and finish the ones that are in progress, choose Actions > Retry failed documents in the app settings.
A document that's already in sevdesk is never created twice. Each order has one invoice record and each refund one credit note record in Swell, written before anything is sent to sevdesk. If sevdesk created a draft but its answer was lost, the app finds the draft by its reference before it creates another. A retry of a document that's in sevdesk only finishes it: finalizing, booking, PDF and e-mail.
If sevdesk can't be reached, is busy or doesn't answer in time, the app tries again for about ten minutes. Then a check every half hour tries the document again. After a day of waiting, it's listed under Needs attention with The document could not be finished within a day.
Every action on orders and documents except Mark as resolved, and Retry failed documents, runs in the background, five documents at a time for a selection. The action shows Running while it works and a message when it finishes, and the result is on the document. The runs are listed under Apps > sevdesk > Workflows. If sevdesk refuses the API token, a run over several documents stops at the first one.
If Swell can't record the document for a paid order or refund, or can't start its run, it sends the event to the app again later, at growing intervals. If that keeps failing for about 4 days, Swell turns off the app's event function and emails the store's admins. Reinstall the app to turn it back on.
When documents need attention, or sevdesk 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 kind of 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 sevdesk needs attention, which you can edit or turn off under Settings > Notifications.
To stop the app from creating a document, for example after you created it in sevdesk by hand or decided none is needed, open it and choose Actions > Mark as resolved. Optionally enter the Document number in sevdesk (optional), then click Mark as resolved. The document's status becomes Resolved by hand, and it's no longer listed under Needs attention.
A document that's in sevdesk but couldn't be finished, for example because its payment couldn't be booked, is marked as In sevdesk instead and left as it is in sevdesk. When an order's invoice was resolved by hand, the app can't build credit notes for it, so its refunds need attention and their credit notes have to be created in sevdesk by hand too.
| Where | What it's for |
| Apps > sevdesk > Settings | The API token, Test connection, the automatic documents switch, and the document and payment settings. |
| Apps > sevdesk > Settings, Actions menu | Retry failed documents. |
| Apps > sevdesk > Workflows | The background runs of the app's actions. |
| Orders > sevdesk documents | Every invoice and credit note, with the Needs attention, In sevdesk, Drafts and Skipped tabs, Open sevdesk, and Retry and Finalize drafts for selected documents. |
| A document | Its number, status, total, problem, PDF, tax rule and payment booking, View in sevdesk, and Retry, Finalize draft, Read again from sevdesk and Mark as resolved in its Actions menu. |
| An order's sevdesk tab | The order's invoice and credit notes, with their status and problem. |
| An order's Actions menu | Create sevdesk invoice. |
| The order list, with orders selected | Create sevdesk invoices. |
| Settings > Notifications | The e-mails sevdesk document for the customer and sevdesk needs attention. |
Settings are in Apps > sevdesk > Settings and are saved separately for each environment. They're in three sections, Connection, Documents and Payments.
| Setting | Description | Default |
| API token | Connection. From your user under Einstellungen > Benutzer in sevdesk. Masked on the settings page. | None |
| Connected account | Connection. Read-only. The name of the sevdesk account the token belongs to, filled in by Test connection. | Not tested yet |
| Create documents automatically for paid orders and refunds | 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, or Finalized documents. A finalized document gets its number, payment booking and PDF at once, and can't be changed or deleted afterwards. | Drafts, to review and finalize |
| Document language | Documents. German, English, or German for DE, AT, CH and LI, English elsewhere, by the billing country. Sets the language of the texts the app writes on the invoice, of the PDF's labels where your sevdesk layout offers it, and of the customer e-mail. Credit notes use their invoice's language. | German |
| Sales to other EU countries | Documents. By the tax rate charged, or Always under the One-Stop-Shop. Decides the sevdesk tax rule of a taxed sale to another EU country. | By the tax rate charged |
| Create credit notes for refunds | Documents. Each refund of an order that has a sevdesk invoice becomes a credit note for that invoice. | On |
| E-mail finalized documents to customers, with a link to the PDF | 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. | Off |
| sevdesk account for shop payments | Payments. The name of the sevdesk account that payments are booked on, as it's written in sevdesk, such as your clearing account. Empty: nothing is booked, and invoices stay open in sevdesk. | None |
| Payment method exceptions | Payments. A row for each payment method that doesn't arrive on the account above. Payment method ID in Swell is the method's ID, such as card, paypal, klarna, amazon, giftcard, account (store credit) or the ID of a manual method. sevdesk account is the account to book it on. Leave it empty to book nothing for the method. Gift cards and store credit are booked only with a row that has an account. | None |
- Only orders in EUR are invoiced.
- Only sevdesk accounts on sevdesk-Update 2.0 are supported.
- Each environment uses the sevdesk account of its API token. There's no test mode, so test orders create real documents there.
- Payments are booked only on sevdesk accounts without a bank behind them. The app can't book payments on a bank or PayPal account connected to sevdesk, where sevdesk matches them from its imported transactions.
- Payouts from your payment provider and its fees aren't booked.
- Status in sevdesk isn't updated when you assign payments or change a document in sevdesk.
- Changes to an order after its invoice, such as edited or canceled items without a refund, aren't sent to sevdesk. 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 sevdesk invoice.
- The app doesn't follow drafts in sevdesk. 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 sevdesk tax rule are listed under Needs attention and have to be invoiced by hand. That includes orders to another country with both shipped items and items that aren't shipped, and a gift card sold with taxed items to another EU country under the One-Stop-Shop.
- Existing sevdesk contacts aren't changed, so a returning customer's new address isn't saved on their contact.
- Customers get a link to the PDF, not an attachment. Anyone with the link can open the PDF.
Problems with a document are shown in Problem on the document, and under Orders > sevdesk documents > Needs attention. The app also logs errors. In the Swell dashboard, the logs are under Developer > Console > Logs.
Enter the API token, save the settings, then test again means no token is saved. sevdesk did not accept the API token means the token is wrong or was replaced. Copy it again from your user under Einstellungen > Benutzer in sevdesk, then save and test again. The sevdesk account uses the bookkeeping system 1.0 means your account isn't on sevdesk-Update 2.0, which sevdesk offers under Einstellungen > System. sevdesk does not allow this for the connected account means the account's plan or the token's user doesn't allow the call.
Check that Create documents automatically for paid orders and refunds 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, aren't invoiced automatically. Choose Actions > Create sevdesk invoice on the order. If the order's document is listed under Needs attention or Skipped, Problem says why.
The token is wrong, was replaced in sevdesk, or isn't saved. The store's administrators get an e-mail whose subject starts with Action needed: sevdesk is not accepting documents from. Copy the token again in sevdesk, paste it in the app settings, save and click Test connection, then choose Actions > Retry failed documents.
The name under Payments doesn't match an account in sevdesk. Test connection lists the accounts that take bookings. Correct the name, save, and choose Retry on the document. The document is already finalized and has its PDF, so the retry only books the payment.
sevdesk books payments on that account only from its imported transactions. Name a clearing account under Payments, or give the payment method a row under Payment method exceptions with no account, so sevdesk matches the payment itself. Then retry.
sevdesk refused the rates under the rule the app chose. The message ends with sevdesk's own answer, which names the rates it allows. Check the store's tax rules for the customer's country, and for sales to other EU countries the setting Sales to other EU countries, then retry. A gift card sold with taxed items to another EU country under the One-Stop-Shop is refused this way, because the One-Stop-Shop rules have no 0 % rate. Create that invoice in sevdesk by hand and mark the document as resolved.
A tax-free invoice to a business in another EU country needs the customer's VAT ID. Check the VAT ID on the order's billing address or customer account, then retry.
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 sevdesk 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 sevdesk account invoices without VAT (§ 19 UStG), but the store charges tax. Correct the tax settings in Swell or in sevdesk, then retry. Orders that were charged tax have to be invoiced by hand.
sevdesk has no tax rule for a foreign rate outside the EU. Create this invoice in sevdesk by hand and mark the document as resolved, and check the store's tax rules for that country.
For a customer in another country, sevdesk books goods and other items under different tax rules, and a document has only one. Create this invoice in sevdesk by hand and mark the document as resolved.
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 sevdesk by hand and mark the document as resolved.
No invoice with exactly the order's total can be built from its amounts. Nothing was numbered in sevdesk. Create the invoice in sevdesk by hand and mark the document as resolved.
Add the name or country to the order's address, then retry. sevdesk does not know the country means the country code isn't in sevdesk's country list.
A refund's credit note waits for its invoice. Correct the invoice's problem and retry it, then retry the credit note.
Finalize the invoice, in Swell with Actions > Finalize draft or in sevdesk followed by Read again from sevdesk. 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 sevdesk by hand and mark it as resolved. The refund of … EUR is more than invoice … still holds means the same.
sevdesk returned the invoice without its positions, so the app can't split the refund by tax rate. Rather than guess the VAT, it doesn't create the credit note. Create it in sevdesk by hand, then mark it as resolved.
A draft was deleted in sevdesk, or the API token now belongs to another sevdesk 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 sevdesk by hand.
The app doesn't know the invoice in sevdesk, so it can't build the credit note. Create the credit note in sevdesk by hand, then mark it as resolved.
sevdesk couldn't be reached or was busy for a day, so the app stopped trying. The rest of the message is the last error. Choose Retry on the document, or Actions > Retry failed documents in the app settings.
Payment booking on the document says why. Usually no account is set under Payments, the payment method has an exception without an account, or the order was paid by gift card or store credit. Drafts aren't booked until they're finalized. When the order was paid after the invoice was created while automatic documents were off, choose Create sevdesk invoice on the order to book the payment.
Drafts have no PDF. Finalize the draft with Actions > Finalize draft, or finalize it in sevdesk and choose Read again from sevdesk.
Check that E-mail finalized documents to customers, with a link to the PDF 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 sevdesk document for the customer is on under Settings > Notifications. Documents finalized before you turned e-mails on are sent when you select them under Orders > sevdesk documents and choose Retry.
Uninstalling the app stops creating invoices and credit notes and booking payments, and removes the app's settings, its functions, the sevdesk documents list, the order's sevdesk 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 API token is deleted from Swell with the settings. Documents that are still in progress aren't finished, because the half-hourly check is removed too. The records under sevdesk documents are kept and come back if you reinstall, so documents already in sevdesk aren't created again. Invoices, credit notes, bookings and contacts in sevdesk stay there.
| Function | Runs on | What it does |
| invoice-order | order.paid, while Create documents automatically for paid orders and refunds is on | Writes the order's invoice record, or marks an existing invoice for booking, and starts a process-documents run. |
| credit-refund | payment.refund.succeeded, while the same setting is on | Writes the credit note record for a refund of an invoiced order, when credit notes are on, and starts a run. |
| process-documents | A workflow, started by the two event functions, sweep, and every action on orders and documents, including Retry failed documents | Works on one document, or on selected documents or orders five per step in id order, until each is complete or needs attention. |
| sweep | Cron, every 30 minutes | Starts a run for documents that wait for sevdesk and had no attempt for 15 minutes. |
| test-connection | The Test connection button | Reads the sevdesk account and payment accounts, checks sevdesk-Update 2.0, saves the account name and clears the connection alert. |
| resolve-document | The Mark as resolved action | Sets the record to resolved, or to created when the document is in sevdesk. |
The app's permissions are read_orders, read_payments and read_accounts. It writes only its own records in Swell.
Each invoice and credit note has a record in the app collection apps/sevdesk/documents, written before anything is sent to sevdesk. Its key, invoice:<order id> or credit_note:<refund id>, is unique, so each order gets one invoice and each refund one credit note. status is pending, created, failed, skipped or resolved, and sevdesk_status is draft, open, partly_paid or paid. Other fields include source, number, invoice_number, order_id, refund_id, payment_method, reference, amount, tax_rule, sevdesk_id, sevdesk_url, contact_id, contact_key, rates, booked_amount, booking_note, date_booked, pdf, problem, problem_code, attempts, date_attempted, date_submitted, date_pending, locked_until and notify_customer. Orders get a documents link field, expanded as $app.sevdesk.documents. Nothing is stored on the order.
The app calls the sevdesk API at https://my.sevdesk.de/api/v1 with the API token in the Authorization header: GET /Tools/bookkeepingSystemVersion, /SevClient, /SevUser and /CheckAccount; GET /CommunicationWay to find contacts by e-mail, and POST /Contact, /ContactAddress and /CommunicationWay; POST /Invoice/Factory/saveInvoice and /CreditNote/Factory/saveCreditNote for drafts (status 100), with the credit note's refSrcInvoice set to the invoice; POST .../render and PUT .../changeParameter for the PDF's language; PUT .../sendBy with sendType VPR to finalize; PUT .../bookAmount on a CheckAccount to book; and GET .../getPdf?preventSendBy=true. Calls time out after 15 seconds, wait 0.5 and 1 second on a 429, and are never repeated after a refusal.
A worker takes a record by raising attempts with $inc and holding locked_until for two minutes, so of two attempts only one goes on. date_submitted is set before a create call and cleared when sevdesk answers. A record still marked on a later attempt is looked up among the contact's drafts by its reference, the order number, or the order number and refund reference for a credit note, after waiting a minute for sevdesk to settle. Before it books, the app reads what sevdesk already holds as paid, and finalizing a finalized document changes nothing.
The tax rule is chosen from the destination country, whether tax was charged, the rates of the taxed lines, the VAT ID, whether items are shipped, and the account's small-business flag. The sevdesk rule ids are 1 (taxable revenue), 2 (export), 3 (intra-community supply), 11 (§ 19 UStG), 17 (not taxable in Germany), 18 and 19 (One-Stop-Shop goods and electronic services) and 21 (reverse charge).
Amounts are integers in 1/10000 EUR. The app simulates sevdesk's line-by-line rounding, half away from zero, and sends net lines only when the simulated gross total equals the order's. Gross lines settle Swell's fractions of a cent between the lines, largest remainder first. A unit price that can't multiply back to its line total with four decimals becomes one line for the lot. The charged tax may differ from the simulated tax by at most 2 cents plus 1 per line.
A run's step for one document retries 5 times, from 20 seconds with exponential backoff; a step over a selection retries 4 times. A sevdesk 429, 5xx or network error sets problem_code to temporary. The sweep picks up records that are pending, or created with a temporary problem, whose date_attempted is older than 15 minutes, and marks a record failed once its date_pending is a day old. A 401, 402 or 403 sets problem_code to connection and stops a run over several records.
Open problems are records in apps/sevdesk/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. Both writes are made from the workflow with $events: true and a $notify name.
Swell builds and maintains the sevdesk app. For help with the app, email support@swell.is. For questions about your sevdesk account, contact sevdesk.