Configuration

Open up the "My Extensions" page: and open the configuration page of the plugin:

Beside these settings, the app needs a connection to your Bexio account, which is set up on its own page in the administration. That is the first step described below.

Connecting the app with Bexio (from app version 1.0.15)

Since app version 1.0.15 the app authenticates with Bexio through Bexio's official login (OpenID Connect). You authorize the app once in Bexio and the connection renews itself from then on – there is no token to copy and no token to renew manually.

Open the connection page in your Shopware administration under Extensions > Bexio connection. It shows one row per scope and operating mode:

Column	Meaning
Scope	"All sales channels (default)" or a single sales channel
Mode	Live or Test
Status	not connected, connected or re-authorization required
Bexio company	The Bexio company ID and the login email the authorization was granted with
Access token	When the access token is renewed the next time (this happens automatically)

To connect, click Connect with Bexio in the row you want to connect. A Bexio login opens in a new tab, you log in with your Bexio user and confirm the access. Afterwards, close the tab and reload the connection page – the row shows connected together with the Bexio company.

Further actions on the page:

1. Reconnect – authorize again, for example after the access was revoked in Bexio or when the invoices should go to a different Bexio company.
2. Disconnect – remove the connection. The app then falls back to the Personal Access Token from the app settings (if one is still stored).
3. Connect a specific sales channel – only needed when a sales channel has to be booked into a different Bexio company than the rest of the shop.

Which credentials are used for an order is resolved in this order:

1. The connection of the sales channel of the order (for the active operating mode).
2. The shop wide connection ("All sales channels").
3. The Personal Access Token from the app settings.

This mirrors how the app settings themselves are inherited in Shopware, so a sales channel specific connection always wins over the shop wide default.

Notes:

• When updating to 1.0.15, Shopware asks you to confirm one additional permission (read access to sales channels). It is only used to list the sales channels on the connection page.
• The app refreshes the connection automatically and additionally runs a daily maintenance job, so a shop with few orders keeps its connection alive as well.
• If Bexio ever refuses to renew a connection (for example because the access was revoked in Bexio), the status changes to re-authorization required and a message is written to the Shopware log. Click Reconnect to fix it. As long as a Personal Access Token is still stored, the app keeps using that one in the meantime.

Personal Access Token (legacy)

The previous authentication with a "Personal Access Token" (PAT) still works and is used as a fallback, but Bexio expires such a token 60 days after it was created, which means a new token has to be pasted into the settings every two months. We therefore recommend connecting the app as described above and clearing the token fields afterwards.

The fields "Live API Token" and "Test API Token" are no longer mandatory. If you don't have two different Bexio environments, you can simply add the very same API key to both fields.

A token can be generated in your Bexio developer account: developer.bexio.com -> Personal Access Tokens -> Create new token -> Generate token.

The connection page lists the expiry date of a stored token and warns you when it expires within the next 14 days. The same warning is written to the Shopware log.

Plugin settings

General

With the selection "Operating mode" you can select which Bexio environment should be used: your production ("Live") or your test Bexio account. This is handy if you have a staging Shopware environment which should send the invoices to the test environment of Bexio. The operating mode decides which credentials are used – both for the new Bexio connection and for the legacy API tokens described above.

Modules

In this section you can enable the different modules of the app. Right now it is only Orders to invoice sync. If enabled, our app generates a new invoice for each new order in your shop depending on the configuration of the payment method.

Orders

In this section you can configure the following things:

1. Bexio user ID: the ID of the Bexio user to whom we assign all invoices.
2. Product description source: whether the position text of a product is taken from Shopware or from the Bexio product catalogue. Only relevant for products with a Bexio Article ID.
3. Product description: Add variant: adds the variant options of a product to the position text (see below).
4. Display Zero-cost shipping option in Bexio invoices: keeps the shipping position on the invoice even when the shipping costs are 0.00.
5. Default tax ID: fallback Bexio tax ID used for positions whose Shopware tax rate has no Bexio tax ID (default: 28).
6. Default account ID: fallback Bexio accounting account for the invoice positions. Leave it empty to let Bexio use the account of the article itself.
7. Show Bexio product code in invoice position: see below.
8. Group bundle products as Bexio position groups: see below.

Customer synchronization

In this section you can configure from which field the email address for the Bexio customer is taken. See Email address for the Bexio customer sync.

Payment methods

The app adds three new custom fields to the Shopware payment methods. You can see them in the payment method detail page in your shopware administration:

There are three fields:

1. Checkbox if orders with this payment methods should generate a Bexio invoice.
2. Select the matching Bexio payment type.
3. Select the matching Bexio bank account.

This is handy if you for example only want to generate invoices for orders with the payment method "Invoice" and not for orders with the payment method "Paypal". With these custom fields, you can configure it to your needs.

The Bexio payment type is used here in the invoice creation process:

The Bexio bank account is used here in the invoice creation process:

as well as for the bank account when marking orders as paid.

The Bexio bank account id is the id of the bank account in Bexio. You can find the bank account id in your bexio account in the URL bar if you click on a bank account in the bank account list: In this example the ID is 1.

Automatic sending of invoices through Bexio

The app adds a custom field to the payment methods to enable the automatic sending of invoices through Bexio. If this is enabled, the invoices in Bexio are not only created but will also be directly sent to the customer.

In Bexio there is a nice log of the sent invoices:

Unfortunately, the API of Bexio does require us to send a email subject and body and we can't use your default email template. Therefore, it is required to fill out the email subject and body in the payment method settings in shopware.

Required placeholder: [Network Link]

The email message must contain the placeholder [Network Link]. Bexio replaces it with the link to the invoice in the Bexio network. This is a requirement of Bexio's send endpoint, not of this plugin.

Two rules apply:

• Plain text only. The placeholder must sit in the visible text of the message. Do not wrap it in a link, e.g. <a href="[Network Link]">. This fails, because the rich text editor URL-encodes the brackets and Bexio no longer recognises the placeholder.
• Per payment method and per language. Subject and message are stored as custom fields on each payment method and are language-specific. Configure every payment method that has invoice sending enabled, in every language the sales channel uses.

No other placeholders are supported

Bexio's own email templates in the Bexio UI support a wide set of placeholders such as [Date], [Document Number], [Needed Payment], [Payable By], [Company Name] and [Website]. These are not available when sending through the API. They are delivered to the customer as literal text.

Write the message without dynamic invoice data. Refer the customer to the attached invoice for invoice number, amount and payment terms, and write static values such as company name and website out in full.

Troubleshooting

Error: 422 while calling /2.0/kb_invoice/{id}/send, errors: message: plugins.ibNetworkPlugin.i18n.form_module_network.error.missing_network_placeholder

Cause: The configured email message does not contain [Network Link], or the placeholder is inside an HTML attribute instead of the visible text.

Effect: The invoice is created in Bexio but not sent. It remains open in Bexio and the customer receives nothing. Check Bexio's sending log to identify invoices affected while the misconfiguration was active.

Fix: Add [Network Link] as plain text to the message of every affected payment method and language, then trigger a test order.

Display of product variants in Bexio invoices

When syncing orders from Shopware to Bexio, it's important to ensure that product variants are correctly displayed in invoices. This setting allows you to control how product descriptions, including variant details, are transferred. Follow the steps below to configure this option properly.

To ensure that product variants are correctly displayed in Bexio invoices, follow these steps:

1. In the Shopware backend, navigate to My Extensions and open the Webwirkung Bexio Integration plugin.
2. Under the Orders modal, enter the correct Bexio User ID.
3. Locate the Product Description Source option and choose whether product descriptions should be taken from Shopware or Bexio.
4. Finally, enable the "Product Description: Add Variant" toggle to ensure that product variants are included in Bexio invoices.

By following these steps, the system will correctly transfer and display product variant information in Bexio invoices.

Manual transmission of orders from Shopware to Bexio on order list level

With the manual transmission feature, you can efficiently transfer multiple orders to Bexio with a single click. This allows for faster processing and better control over order synchronization. To ensure a successful transmission, make sure that the correct Bexio IDs for products, shipping, and taxes are properly configured. Incorrect or missing IDs may result in transmission errors or incomplete data synchronization.

Important: Manual transmission is also working, if the general order transmission in the bexio setting is deactivated.

Check rounding setting in Shopware currency settings

Bexio applies a rounding factor of 0.05 to the invoice grand total. Please ensure your Shopware currency settings are aligned accordingly.

To do this, navigate to Settings > Currencies, select your active currencies, and set the 'Grand total rounding' interval to 0.05.

Synchronization of payment status from Bexio to Shopware

The integration allows you to automatically synchronize the payment status from Bexio back into Shopware. This ensures that payments registered in Bexio are also reflected in the Shopware order status.

1. Only orders from the last 6 months are checked.
2. A configuration option is available in the plugin settings.

3. The synchronization runs automatically every 24 hours at 01:00 AM.
4. This feature is useful if you want to keep your Shopware order statuses up to date without manual adjustments.

Tax mapping

The app adds a custom field to map your tax rates to the Bexio tax rates.

Please make sure that these ids are correct. Otherwise, the invoice creation will fail.

You can find the ids in your Bexio account here. The id is visible in the URL of the tax rate in the detail view in bexio. In this example the ID is 13:

Accounting accounts of the invoice positions

By default, the invoice positions are booked to the account that is configured on the article in Bexio. Two settings allow you to override this:

1. Default account ID (app settings, "Orders" section): the Bexio account used for all invoice positions.
2. Bexio: Account ID (custom field on the customer group, from app version 1.0.15): the Bexio account used for the invoice positions of customers in this customer group.

You will find the custom field in the Shopware administration under Settings > Customer groups in the detail page of a customer group. The field accepts either the account number as it is shown in Bexio (e.g. 3000) or the internal account ID – the app resolves the number to the internal ID itself.

The account of a position is resolved in this order:

1. The account of the customer group of the ordering customer.
2. The "Default account ID" from the app settings.
3. No account at all – Bexio then falls back to the account of the article.

This lets you book different customer groups to different accounting accounts, for example a B2B group to another revenue account than private customers.

Notes:

• The field is empty by default, so existing installations are unaffected.
• If the value matches neither an account number nor an account ID in Bexio, the app ignores it, falls back to the default account and writes a warning to the Shopware log.
• Shipping positions always use the "Default account ID" and are not affected by the customer group account.

Shipping method

By default, we write a custom position for the shipping costs in the invoice in Bexio and use the default tax ID 28. However this can be changed in the shipping method settings in shopware. Please have a look at the custom fields in the shipping method detail page:

Here you can add the Bexio product id to map the shipping method to a Bexio product and also the tax id.

Please remember that the bexio product id is the id of the product in Bexio. You can find the product id in your bexio account in the URL bar if you click on a product in the product list:

This allows you to map different shipping methods to different Bexio products.

Salutations

The app adds a custom field to salutations to map your salutations to the Bexio salutations. When the Bexio salutation id is filled out, the app will use this salutation id for the invoice creation.

In shopware, it is a new custom field in the salutation detail page:

In Bexio, you can find the salutation IDs in the setting You can find the salutation ID in your bexio account in the URL bar if you click on a salutation in the salutation list:

(Optional) Product ID

The app adds a custom field to products to map your products to the Bexio products. When the Bexio product id is filled out, the app will use this product id for the invoice creation. Otherwise, we just create a new custom position. The difference is shown below. In Bexio, it is marked with a different icon.

Product ID in Shopware

There is a new custom field in the product detail page:

Product ID is filled out

Product ID is not filled out

Also, if the product ID is set, the product name and description of Bexio is used for the invoice and the product name and description coming from Shopware are ignored.

Please make sure that the product id is correct if you decide to use this feature. Otherwise, the invoice creation will fail.

You can find the product ID in your bexio account in the URL bar if you click on a product in the product list:

In the future we might support the usage of the product number instead of the product id.

(Optional) Display Bexio product code in invoice positions

When a Shopware product has a Bexio Article ID configured, Bexio normally resolves the product name itself when creating invoice positions via the API. However, unlike manually added positions in Bexio, the product code (e.g. BAPB100) is not automatically shown in the position text.

This setting allows you to enable that behaviour explicitly. When active, the plugin fetches the product code (intern_code) from Bexio for each position that has a Bexio Article ID and formats the position text to match what Bexio shows when a product is added manually:

Product name
Produktcode: BAPB100

To enable this, open the plugin configuration in the Shopware administration and activate the "Show Bexio product code in invoice position" toggle under the Orders section.

Notes:

• Disabled by default. Existing clients are unaffected unless the option is explicitly activated.
• Only applies to products that have a Bexio Article ID set. Products without one continue to be transferred as custom positions.
• The product name shown in the position text respects the existing Product Description Source setting: if set to "Shopware", the Shopware product name is used; if set to "Bexio", the article name from Bexio is used.

Email address for the Bexio customer sync

By default, the app syncs the email address of the Shopware customer account to the Bexio contact and uses it for the duplicate check. From app version 1.0.15, the email address can instead be taken from a custom field of the billing address of the order.

This is useful when several Shopware accounts belong to the same invoice recipient (e.g. several buyers of one company) and all of their orders should end up on one single Bexio customer.

To enable it, open the plugin configuration and enter the technical name of the custom field into the field "Source email from custom field" in the "Customer synchronization" section (e.g. custom_invoice_email). The custom field has to be created by you on the customer address entity (Settings > Custom fields, entity "Customer address"), so you can fill it in the administration or in your storefront.

When the option is set, the app:

1. Reads the value from the billing address of the order.
2. Writes it as the email address of the Bexio contact.
3. Uses it as the matching key of the duplicate check, so orders of different Shopware accounts with the same invoice email address are assigned to the same Bexio contact.
4. Uses it as the recipient address when the automatic invoice sending through Bexio is enabled.

Notes:

• The option is empty by default. Existing installations keep syncing via the customer account email address.
• The custom field has to be filled before the order is placed. Shopware copies customer address custom fields into the order address at checkout, so filling the field afterwards does not change orders that already exist.
• If the custom field is missing, empty or does not contain a valid email address, the sync falls back to the customer account email address and writes a warning to the Shopware log.
• Whether the invoice is booked on a company contact or on a person contact is still decided by the company field of the billing address of the order.

Product boxes and bundles as position groups

If your shop sells product boxes, bundles or configurator sets, the line item of the box in Shopware contains its child items. Without this option only the child items are transferred and the price of the box itself is lost, so the Bexio invoice total can be lower than the Shopware order total.

From app version 1.0.15 you can activate the option "Group bundle products as Bexio position groups" in the "Orders" section of the plugin configuration. When active, every line item with child items becomes a Bexio group position that contains:

• The child items of the box as individual positions.
• One additional position for the difference between the price of the box and the sum of its child items (if there is one).

This way the invoice shows the content of the box and the Bexio total matches the Shopware order total again.

Notes:

• Disabled by default. Existing clients are unaffected unless the option is explicitly activated.
• The positions of a group use the same tax ID, account and product description settings as normal positions.
• If Bexio rejects one of the group positions, the app deletes the incomplete draft invoice again so no half filled invoice stays behind in Bexio, and logs the reason.

FAQ

What should I check if my orders are not being transmitted?

• The plugin is installed and activated.
• The credentials are valid: either the Bexio connection under Extensions > Bexio connection shows "connected" for the active operating mode, or a valid Personal Access Token is stored in the plugin configuration (NOTE: Bexio expires such a token 60 days after it was created).
• Check in the plugin configuration whether the toggle "Module Orders" is activated.
• The taxes used in the line items of an order have a correct Bexio tax ID.
• For the payment method used in the order, the “Bexio: Create invoice” checkbox is activated and a valid Bexio payment method is selected.