README

Vertex Tax Integration for Shopware 6

Introduction

The Vertex Tax Integration Plugin connects your Shopware 6 store to the Vertex O Series REST API, enabling real-time, automated tax calculation at checkout. Vertex is a leading tax compliance engine trusted by businesses worldwide to handle complex tax rules across jurisdictions.

This plugin supports the full order tax lifecycle — from real-time calculation during checkout to transaction commits on order placement and reversals on cancellation or refund. It also provides address validation, B2B tax exemption handling, and a comprehensive logging system for full visibility and compliance confidence.

Key Features

Real-Time Tax Calculation

• Calculates accurate taxes during checkout using the Vertex O Series REST API v2.

OAuth 2.0 Authentication

• Secure API authentication with token caching to minimize redundant auth requests.

Full Order Lifecycle Management

• Automatically commits transactions on order placement, payment, or shipment (configurable).
• Automatically reverses transactions on order cancellation or refund.

Address Validation

• Validates customer addresses against Vertex's address database for accurate jurisdiction-based tax calculation.

Product & Shipping Tax Code Mapping

• Map product-level tax codes via custom fields and configure a dedicated shipping tax code.

B2B Support

• Handles VAT ID verification and tax exemption logic for business customers.

Multi-Environment Support

• Switch between Production and Sandbox Vertex environments via configuration — no code changes required.

Debug Mode

• Enable debug logging to troubleshoot API communication and tax calculation issues.

API Connection Testing

• Built-in endpoint to test your Vertex API connection directly from the Shopware Admin.

Comprehensive Logging

• Full logging of API requests, responses, and tax events for audit and troubleshooting purposes.

Compatibility

• ✅ Shopware 6.7+
• ✅ PHP 8.1+

Get Started

Installation & Activation

GitHub

1. Clone the plugin into your Shopware plugins directory:

git clone https://github.com/solution25com/vertex-tax-shopware-6-solution25.git custom/plugins/VertexTax

1. Install the Plugin in Shopware 6

   • Log in to your Shopware 6 Administration panel.
   • Navigate to Extensions > My Extensions.
   • Locate the plugin and click Install.

2. Activate the Plugin

   • After installation, click Activate to enable the plugin.
   • Run the following commands from your Shopware root:

bin/console plugin:refresh
bin/console plugin:install --activate VertexTax
bin/console cache:clear

1. Verify Installation

   • After activation, you will see Vertex Tax Integration in the list of installed plugins.
   • The plugin name, version, and installation date should appear.

Plugin Configuration

After installing the plugin, configure your Vertex credentials and options through the Shopware Administration panel.

Accessing the Configuration

1. Go to Settings > Extensions > Vertex Tax Integration
2. Select the Sales Channel you want to configure
3. Set the following fields:

General Settings

API Credentials

Tax Code Settings

Transaction Settings

Origin Address

The origin address is used by Vertex to determine the correct tax jurisdiction for shipments.

How It Works

1. Tax Calculation at Checkout

When a customer proceeds through checkout, the plugin sends the cart contents and customer address to the Vertex O Series REST API in real time. Vertex returns the applicable tax amounts per line item, which are applied to the Shopware cart before the customer confirms the order.

2. Address Validation

The plugin validates the customer's shipping address against Vertex's address service to ensure the correct tax jurisdiction is applied.

3. Transaction Commit

Once an order is placed (or paid/shipped, depending on your Commit Tax Flow setting), the plugin commits the transaction to Vertex — creating a permanent tax record for compliance and reporting purposes.

4. Transaction Reversal

If an order is cancelled or refunded, the plugin automatically sends a reversal transaction to Vertex to keep your tax records accurate and up to date.

5. Product Tax Code Mapping

Individual products can be assigned a Vertex tax code via Shopware custom fields, enabling precise tax treatment per product category or type. If no code is set on a product, the Default Product Tax Code from configuration is used as a fallback.

Uninstallation

bin/console plugin:deactivate VertexTax
bin/console plugin:uninstall VertexTax
bin/console cache:clear