Connect your Shopware store to Kintsugi so Kintsugi becomes your store's tax provider. Once connected, Kintsugi calculates sales tax at checkout and records your completed orders for nexus tracking and filing.
In this guide:
Download and install the Kintsugi extension
Create Shopware API credentials
Configure your Shopware tax settings
Connect Shopware to Kintsugi
Verify your connection
Scale or Premium Plan Required
Tax engine integrations are available on the Scale and Premium plans. If you are on the Starter or Free plan, upgrade before you start. To check your plan, go to Configuration > Billing Details.
Have these ready so setup goes smoothly in one sitting:
A Kintsugi account you can sign in to.
Administrator access to your Shopware admin panel.
Your storefront domain, for example myshop.com.
A Scale or Premium Kintsugi plan if you want tax calculated at checkout. See Plan Requirements below.
Download the extension. Open the Shopware Plugins File Index and click the zip file under Latest File. Always use the latest file, since it includes the newest connection flow.
Unzip the download. Inside you will find two files: Kintsugi.zip (the extension you will upload) and Instruction.txt (a link back to this guide). Do not unzip Kintsugi.zip.
Open the upload window. In your Shopware admin, go to Extensions > My extensions and click Upload extension at the top right.
Upload Kintsugi.zip. Click Choose file and select Kintsugi.zip. Tick the box that reads "I understand that extensions, not listed in the Shopware Store, could pose a risk to my shop", then click Continue.
Tip: Keep a copy of Kintsugi.zip on your computer. Shopware does not let you download an extension again after it is uploaded.
Activate the extension. On the My extensions page, turn on the toggle next to Kintsugi Sales Tax Autopilot.
Success check: The toggle is on (blue) and the extension shows its version number and install date.
Kintsugi connects through a Shopware integration. The integration lets Kintsugi read your products, customers, and orders, and write tax results back to your orders. Choose one of the two options below.
Option | Best for |
|---|---|
Option A: Administrator access | The fastest setup. The integration gets full access to your shop. |
Option B: Custom role | Stores that want to limit the integration to only the permissions Kintsugi needs. |
In your Shopware admin, go to Settings and click Integrations under System.
Click Add integration.
Enter Kintsugi as the name and turn on the Administrator switch.
Copy and save these two values somewhere secure:
Access key ID (this is your Client ID)
Secret access key (this is your Client Secret)
Important: Shopware shows the secret access key only once. If you lose it, create a new integration to get a new one.
Click Save integration.
Go to Settings > Users & permissions. In the Roles section, click Create role.
Enter a role name, for example Kintsugi, then grant the permissions in the table below.
Permission area | Access needed |
|---|---|
Categories | View |
Custom Products | View |
Products | View |
Customers | View |
Orders | View, Edit |
Refunds | View, Edit |
Order | Create credit items |
Promotion | View |
Tip: To save time, tick the All checkbox on each of the rows above.
Click Save and enter your Shopware password when asked.
Go to Settings > Integrations and click Add integration. Enter Kintsugi as the name, leave the Administrator switch off, and select your new role in the Roles field.
Copy and save the Access key ID (Client ID) and Secret access key (Client Secret), then click Save integration.
Complete these settings before you connect, so Kintsugi can calculate tax correctly from your first order.
Go to Settings > Customer groups and open Standard customer group.
Under Tax display, select Net.
Click Save, then refresh the page.
Why this matters: Kintsugi adds sales tax on top of your prices. With Gross selected, Shopware treats prices as already including tax.
Go to Settings > Tax.
Under Tax provider, find Kintsugi. If its switch is off, turn it on so it shows Active.
Next to Kintsugi, click Edit details.
Under Availability rule, choose the customers Kintsugi should calculate tax for:
All customers
Customers from USA
A custom rule you create in Settings > Rule builder
Click Save.
Note: The extension sets Kintsugi's Priority to 1 automatically, so you do not need to change it.
Go to Extensions > My extensions. On Kintsugi Sales Tax Autopilot, click the three-dot menu and select Open extension.
The Connect Kintsugi screen shows a secure sign-in link made for your store. Click Open Kintsugi.
Note: This link works once and expires after about 10 minutes. The screen shows how much time is left. If it runs out, click Get a new link.
Kintsugi opens with the Shopware connection card. If you are asked to sign in, sign in to your Kintsugi account first.
Fill in the connection card:
Shop Domain: your storefront domain, for example myshop.com. The field already includes https://, so enter the domain only, with no slashes.
Client ID: the Access key ID you saved in Step 2.
Client Secret: the Secret access key you saved in Step 2.
Click Save, then click Authorize.
Success check: The card status changes from Unauthorized to Active.
Reconnecting an existing store? If your store was connected before, opening the extension shows an option to re-authorize or re-activate the connection, along with a button that opens Kintsugi. Follow it to restore your connection.
In Kintsugi, go to Data Sources.
Under Manage Integrations, confirm that Shopware shows as Active.
If Shopware shows as Active, you are all set.
Tax is calculated at checkout. Kintsugi calculates sales tax while your customer checks out.
Orders reach Kintsugi when they are Done. An order is recorded in Kintsugi only after its order status is set to Done.
Address changes after checkout are not recalculated. If an order needs a different address, cancel it and have your customer place a new order. Editing the address in your Shopware admin does not recalculate tax.
Tax calculation at checkout (tax estimation) and real-time order updates through webhooks are not available on the Free plan. To use Kintsugi as your Shopware tax provider, make sure your organization is on a Scale or Premium Kintsugi plan.
What you see | What to do |
|---|---|
The Open Kintsugi link has expired | Click Get a new link on the Connect Kintsugi screen. If the screen does not respond, reload the page in your Shopware admin and open the extension again. |
Kintsugi is missing under Tax provider | Check that the extension toggle is on in Extensions > My extensions, then refresh Settings > Tax. |
The connection card stays Unauthorized | Click Save first, then Authorize. Check that the Shop Domain has no https:// and no slashes, and that the Client ID and Client Secret match your Shopware integration. |
You lost your Client Secret | Shopware cannot show it again. Create a new integration (Step 2) and enter the new credentials on the connection card. |
No tax appears at checkout | Confirm that tax display is Net, Kintsugi is Active under Tax provider, the availability rule includes the customer, and your organization is on a Scale or Premium plan. |
An order is missing in Kintsugi | Set the order status to Done in Shopware. Orders in other statuses are not recorded yet. |
Which option should I pick in Step 2?
Both work the same way for Kintsugi. Option A is quicker. Option B limits the integration to only the permissions in the table, which some teams prefer for security.
Why does Kintsugi need Edit access to orders and refunds?
Kintsugi writes the calculated tax back to your orders and handles tax on refunds and credits. The other permissions are view only.
Do I need to reinstall the extension when a new version comes out?
Download the newest file from the Shopware Plugins File Index and upload it through Upload extension. Shopware uses the same window to update an extension you already installed.
What is the difference between a tax engine and a read-only integration?
A tax engine integration calculates tax for your customers. A read-only integration only imports your data. Learn more in Understanding Read-only vs. Tax Engine Integrations in Kintsugi.
Most connection issues are solved in a few minutes with the Troubleshooting table above. If you are still stuck, click the chat bubble in the bottom-right corner and include your shop domain and a screenshot of what you see. That helps our team resolve it faster.