Shopware Tax Engine Integration Guide

This guide will walk you through the simple steps to integrate Kintsugi with your Shopware store.
​

Step 1: Download and Install the Extension

1. Download the extension:
   Get the latest Kintsugi zip file from the Shopware Plugins File Index. Always choose the most recent version to ensure you’re installing the most updated version.

   ​

2. Extract the file:
   Unzip the downloaded zip file. You’ll find another zip file inside named Kintsugi.zip.
   
   ​

3. Upload to Shopware:

   1. In your Shopware admin panel

   2. Go to Extensions → My Extensions

   3. Click Upload Extension (at the top right corner)

      

   4. Select Kintsugi.zip to upload
      

4. Activate the app:
   Once uploaded, activate the Kintsugi app.

   

✅ Success! If the extension is active, you’ve successfully installed it.

Step 2: Obtain Shopware Credentials

You have two options to add Kintsugi as an integration.

Option A: Quick Setup (Administrator Switch)

This method is recommended for ease of setup, as Kintsugi primarily reads data.

1. Go to Integrations:
   In your Shopware admin, go to Settings → Integrations.

   

2. Add Integration:
   Click “Add Integration”.

   

3. Enter Name:
   Type “Kintsugi” to the integration’s name box
   ​

4. Save Credentials:
   Copy and securely save the following credentials; you’ll need them later:

• Access Key ID (Client ID)

• Secret Access Key (Client Secret)​

5. Click “Save Integration”

Option B: Custom Role Setup:

If you prefer not to use the Administrator switch, you can create a custom role with specific permissions.

1. Create Role:
   In your Shopware admin, go to Settings → System → Users & Permissions → Roles. Click Create role.

   

2. Select your permissions

For our extension to work properly, below is the list of entities we need permission for:

• Categories - [View]

• Custom Products - [View]

• Products - [View]

• Customers - [View]

• Orders - [View, Edit]

• Refunds - [View, Edit]

• Order - [Create credit items]

• Promotion - [View]

Upon saving your changes, you will be prompted to confirm with your password.

3. Return to Add Integration again
   Select the Kintsugi integration you created.
   

4. Select your Roles
   
   Don't forget to copy the Access ID & Secret Access Key

5. Click Save.

Step 3: Configurations & Mandatory Settings

Before connecting Kintsugi, ensure these settings are applied:
​

1. Set Customer Group to “Net”

• Go to Settings → Customer Groups → Standard Customer Group.

• Select Net as the tax display.

• Click Save and refresh the page.

• 

2. Enable Kintsugi as a Tax Provider

• Go to Settings → Tax.

• Ensure Kintsugi appears as a tax provider. If not, toggle the switch to activate it.

• 

• Click Edit details.

• Set Priority to 1 (so Kintsugi calculates taxes first).

• Under “Availability,” select All customers or Customers from USA, depending on your use case.

• Click Save.

• 

Step 4: Connect Shopware with Kintsugi

1. Go to Extensions → My Extensions.

   

2. Find Kintsugi, click the three-dot menu (⋮) on the right, and select Open Extension.

   

3. If prompted, sign in to your Kintsugi account.

   

   • If the pop-up is blocked, click the provided link to open it manually.

4. Select your Organization to continue.

   

5. Go to Data Sources.

   

6. Click Browse Integration.

   

7. Find Shopware and click Connect.

   

8. In the pop-up card, enter the credentials you saved earlier:

   • Shop Domain (your store’s main domain, e.g., myshop.com, without slashes)

   • Client ID

   • Client Secret

   

9. Click Save, then Authorize.

Once connected, the card will display as Active, confirming the integration was successful. 🎉

Step 5: Verify Your Connection

To ensure that the integration is a success, follow the steps below.

1. Navigate to Data Sources.

   

2. Check Manage Integrations, Shopware should appear in the "Active" tab.

If you see a screenshot similar to the one above, you’re all set!

Important Notes

• Kintsugi calculates taxes during the checkout process.

• If an address change is needed after checkout, you need to cancel and re-create the order as Shopware won’t recalculate taxes post-checkout.

• Orders are committed to Kintsugi only when the order status is “Done.”

• Tax-engine features (such as tax estimation and webhook services) are exclusively available to premium customers.

Need Help?

For further concerns, we're always here to help. If you can't find the answer you're looking for, please reach out to us via the chat bubble in the bottom-right corner.