WooCommerce Tax Engine Integration Guide

Overview

The WooCommerce tax-engine integration ensures that every order in your store is taxed accurately and in compliance with state rules. Once connected, your transactions will automatically sync to Kintsugi, where you can review, approve, and manage them.

Step 1: Generate API Keys in WooCommerce

1. Log in to your WooCommerce Admin.

2. Go to Settings, then Advanced, then REST API.

3. Click Add Key and set permissions to Read/Write.

   A quick note on user roles

   Your WooCommerce API key inherits the permissions of the WordPress user it was created under. If that user has a lower-privilege role, your store's products will still sync, but any endpoint that touches orders or refunds will fail with a 403 error.

   The API key must belong to a WordPress user with the Administrator or Shop Manager role. The Editor, Author, Contributor, and Customer roles will all 403 on orders and refunds.
   

   Check or fix the user role:

   • Log in to WordPress Admin

   • Go to Users, then All Users

   • Select the user tied to your API key

   • Confirm the user's role

   • If the role is Editor, Author, Contributor, or Customer, change it to Shop Manager or Administrator
     

   Still failing? Regenerate the key:

   • Go to WooCommerce, then Settings, then Advanced, then REST API

   • Select the existing key, or add a new one

   • Set the permission to Read/Write

   • Regenerate the key if the role was recently changed

   • Reconnect in Kintsugi using the new Consumer Key and Secret

4. Copy the Consumer Key (starts with ck_) and Consumer Secret (starts with cs_). You’ll need these later.

Step 2: Connect WooCommerce to Kintsugi

1. Log in to your Kintsugi account.

2. Click Data Sources from the left navigation panel.

3. Click Browse Integration to proceed with he process.

4. Look for WooCommerce and click Connect.

5. A modal window will open, enter the following details:

• Shop Domain (your WooCommerce store domain).

• Admin URL (your WooCommerce admin panel URL).

• Consumer Key (ck_...).

• Consumer Secret (cs_...).

• Click Save.

Step 3: Install the Kintsugi Plugin in WooCommerce

1. Get the Kintsugi WooCommerce Plugin. Click HERE to download the latest version of the SalesTax plugin (it will be a ZIP file).

2. In WooCommerce, go to Plugins > Add Plugin.

3. Click Upload Plugin and select the Kintsugi WooCommerce plugin .zip file.

4. Wait for the plugin to finish installing and activating.

Step 4: Activate the API key

1. Generate your API key in Kintsugi, you may refer to this help article: Mastering API Keys: Creation, Management, and Security

2. After generating the API key in the Kintsugi app, copy and paste it into the Kintsugi plugin settings within WooCommerce.

3. Go to WooCommerce > Kintsugi to access plugin settings.

4. Click Connect to Kintsugi.

You’ll see a green confirmation message:

“Connected to Kintsugi

Your store is connected to Kintsugi and you can disconnect at any time.”

Step 5: Enable Tax Collection and Webhooks

In the plugin settings, check the box Enable Kintsugi Tax Collection and Webhook Processing.

• When enabled, tax calculations and webhooks will run automatically.

• When disabled, tax processing will stop.

Confirm the connection status shows:

Step 6: Verify Integration in Kintsugi

1. Go to Data Sources and check Manage Integrations. You should see WooCommerce under the "Active" tab.

   

2. Go to the Transactions tab in Kintsugi.

3. Review your synced WooCommerce transactions, including:

   • Transaction ID and date

   • Customer details

   • Jurisdiction

   • Tax liability

   • Collected tax

   • Transaction status

4. Click a transaction to see detailed order, product, and payment information.

   

Step 7: Test Tax Calculation in WooCommerce

1. Add products to your cart and proceed to checkout.

2. The cart totals will show subtotal, shipping, tax, and total.

3. Complete checkout with your preferred payment method.

4. Refresh the Transactions tab in Kintsugi—your order will appear instantly with all tax details.

Step 8: Complete Your Dashboard's Pending Tasks section.

• Verify the following integration data:

  • Products: Kintsugi AI automatically assigns categories and subcategories to products, but you must review and approve them, as not all products are taxed the same.

    For guidance on classifying products, see the help article: Updating Product Category and Subcategory. You can also set a default classification for new synced products: How to Set a Default Product Classification.

  • Invalid and Blank Addresses: In many jurisdictions in the US, sales tax is assessed based on the ship-to address, so you need to ensure the accuracy of the addresses of your transactions. Check out these help articles: How to Update Invalid Addresses in the Kintsugi App and How to Update Blank Addresses in the Kintsugi App

• Review and confirm that the visibility of your transactions, customers, and products are synced successfully in the Kintsugi dashboard.

  You're all set! Kintsugi will begin calculating and monitoring where you have exposure or have reached nexus and where you need to register.

  By keeping your WooCommerce Tax Engine Integration active and properly configured, Kintsugi maintains accurate reporting based on your store's transaction data.

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 using the chat bubble in the bottom right corner.