Tax provider

Tax calculations differ from country to country. Especially in the US, the sales tax calculation can be tedious, as the laws and regulations differ from state to state, country-wise, or even based on cities. Therefore, most shops use a third-party service (so-called tax provider) to calculate sales taxes.

With version 6.5.0.0, Shopware allows apps to integrate custom tax calculations, which could include an automatic tax calculation with a tax provider. An app has to provide an endpoint, which is called during the checkout to provide new tax rates. The requests and responses of all of your endpoints will be signed and featured as JSON content.

Prerequisites

You should be familiar with the concept of Apps, their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server.

App Base Guide

Your app server must be also accessible for the Shopware server. You can use a tunneling service like ngrok for development.

Manifest configuration

To indicate to Shopware that your app uses a custom tax calculation, you must provide one or more tax-provider properties inside a tax parent property of your app's manifest.xml.

Below, you can see an example definition of a working tax provider.

<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <!-- The name of the app should not change. Otherwise all payment methods are created as duplicates. -->
        <name>PaymentApp</name>
        <!-- ... -->
    </meta>
    <tax>
        <tax-provider>
            <!-- Unique identifier of the tax provider -->
            <identifier>myCustomTaxProvider</identifier>
            <!-- Display name of the tax provider -->
            <name>My custom tax provider</name>
            <!-- Priority of the tax provider - can be changed in the administration as well -->
            <priority>1</priority>
            <!-- Url of your implementation - is called during checkout to provide taxes -->
            <process-url>https://tax-provider.app/provide-taxes</process-url>
        </tax-provider>
    </tax>
</manifest>

After successful installation of your app, the tax provider will already be used during checkout to provide taxes. You should also see the new tax provider showing up in the administration in Settings > Tax.

Tax provider endpoint

During checkout, Shopware checks for any active tax providers - sorted by priority - and will call the processUrl to provide taxes one-by-one, until one of endpoint successfully provides taxes for the current cart.

WARNING

Connection timeouts

The Shopware shop will wait for a response for 5 seconds. Be sure, that your tax provider implementation responds in time, otherwise Shopware will time out and drop the connection.

In response, you can adjust the taxes of the entire cart, the entire delivery, or each item in the cart.

If you wish to use a tax provider, you will probably have to provide the whole cart for the tax provider to correctly calculate taxes during checkout and you will probably get sums of the specific tax rates, which you can respond to Shopware via cartPriceTaxes. If given, Shopware does not recalculate the tax sums and will use those given by your tax provider.