/ /

Shopware Tax Engine Integration Guide

Install the Kintsugi extension in Shopware, create API credentials, configure tax settings, and connect your store using the new secure sign-in link.
Updated 10 days ago

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:

  1. Download and install the Kintsugi extension

  2. Create Shopware API credentials

  3. Configure your Shopware tax settings

  4. Connect Shopware to Kintsugi

  5. 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.

Before You Begin

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.

Step 1: Download and Install the Extension

  1. 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.

  2. 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.

  3. Open the upload window. In your Shopware admin, go to Extensions > My extensions and click Upload extension at the top right.

    My extensions page with the Upload extension button highlighted

  4. 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.

    Upload private extension dialog with Kintsugi.zip selected and the risk checkbox ticked

    Tip: Keep a copy of Kintsugi.zip on your computer. Shopware does not let you download an extension again after it is uploaded.

  5. Activate the extension. On the My extensions page, turn on the toggle next to Kintsugi Sales Tax Autopilot.

    Kintsugi Sales Tax Autopilot extension with the activation toggle turned on

Success check: The toggle is on (blue) and the extension shows its version number and install date.

Step 2: Create Shopware API Credentials

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.

Option A: Administrator Access

  1. In your Shopware admin, go to Settings and click Integrations under System.

    Shopware Settings page with Integrations highlighted under System

  2. Click Add integration.

    Integrations page with the Add integration button highlighted

  3. Enter Kintsugi as the name and turn on the Administrator switch.

    Create integration window showing the Name field, Administrator switch, and access keys

  4. 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.

  5. Click Save integration.

Option B: Custom Role

  1. Go to Settings > Users & permissions. In the Roles section, click Create role.

    Users and permissions page with the Create role button highlighted

  2. 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.

Create role permissions grid with the All column checkboxes highlighted

  1. Click Save and enter your Shopware password when asked.

  2. 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.

    Create integration window with the Roles dropdown open

  3. Copy and save the Access key ID (Client ID) and Secret access key (Client Secret), then click Save integration.

Step 3: Configure Your Shopware Tax Settings

Complete these settings before you connect, so Kintsugi can calculate tax correctly from your first order.

3.1 Set Tax Display to Net

  1. Go to Settings > Customer groups and open Standard customer group.

  2. Under Tax display, select Net.

  3. Click Save, then refresh the page.

    Standard customer group with Tax display set to Net

Why this matters: Kintsugi adds sales tax on top of your prices. With Gross selected, Shopware treats prices as already including tax.

3.2 Make Sure Kintsugi Is an Active Tax Provider

  1. Go to Settings > Tax.

  2. Under Tax provider, find Kintsugi. If its switch is off, turn it on so it shows Active.

    Tax settings page showing Kintsugi under Tax provider with the Active switch on

3.3 Choose Which Customers Kintsugi Calculates Tax For

  1. Next to Kintsugi, click Edit details.

  2. 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

    Kintsugi tax provider details with the availability rule dropdown open

  3. Click Save.

Note: The extension sets Kintsugi's Priority to 1 automatically, so you do not need to change it.

Step 4: Connect Shopware to Kintsugi

  1. Go to Extensions > My extensions. On Kintsugi Sales Tax Autopilot, click the three-dot menu and select Open extension.

    Three-dot menu on the Kintsugi extension with Open extension highlighted

  2. The Connect Kintsugi screen shows a secure sign-in link made for your store. Click Open Kintsugi.

    Connect Kintsugi screen with the Open Kintsugi button and the link expiry timer

    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.

  3. Kintsugi opens with the Shopware connection card. If you are asked to sign in, sign in to your Kintsugi account first.

  4. 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.

    Shopware connection card in Kintsugi with Shop Domain, Client ID, and Client Secret fields

  5. 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.

Step 5: Verify Your Connection

  1. In Kintsugi, go to Data Sources.

  2. Under Manage Integrations, confirm that Shopware shows as Active.

    Kintsugi Data Sources page showing Shopware as Active under Manage Integrations

If Shopware shows as Active, you are all set.

How Tax Works With This Integration

  • 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.

Plan Requirements

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.

Troubleshooting

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.

Frequently Asked Questions

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.

Need Help?

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.

Was this article helpful?