gokarla / shopware

v1.2.6 2026-09-28 15:38 UTC

Requires

• shopware/administration: *
• shopware/core: *
• shopware/storefront: *

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• phpstan/phpstan: ^1.12
• phpunit/phpunit: ^11.0
• rector/rector: ^1.2

Apache-2.0

• GoKarla GmbH

Published on Packagist.org on 2026-09-28 15:41 UTC

README

Enhance your post-purchase customer experience in Shopware with GoKarla - automated order tracking and delivery updates for your customers.

Overview

The Karla Delivery extension automatically synchronizes your Shopware orders and shipments with GoKarla, enabling you to provide your customers with precise, timely delivery updates and improve satisfaction after purchase.

Features

Core Capabilities

• Automatic Order Synchronization - Orders are automatically sent to GoKarla when placed or updated
• Shipment Tracking Integration - Delivery tracking codes are synchronized in real-time
• Customer Segmentation - Leverage order and customer tags for targeted communication
• Multi-Channel Support - Map different sales channels to specific GoKarla shops

Flexible Configuration

• Configurable Event Triggers - Choose which order and delivery statuses trigger synchronization
• Line Item Type Mapping - Support for products, promotions, and custom line item types (e.g., deposits)
• Custom API Endpoint - Use production or custom GoKarla API endpoints
• Detailed Logging - Built-in logging for troubleshooting and monitoring

Signed Tracking Links in Shopware Emails

After a successful order sync, the extension stores an authenticated Karla tracking link in the order custom field karla_trackpage_url. A native Shopware mail template can use it without letting Karla send the email:

{% if order.customFields.karla_trackpage_url %}
    <a href="{{ order.customFields.karla_trackpage_url }}">Sendung verfolgen</a>
{% endif %}

Keep the existing postcode-authenticated tracking link as a fallback for historical orders that do not yet have the custom field. Treat the signed URL as a customer credential: do not expose it in logs or admin exports.

Requirements

• Shopware 6 - Compatible with Shopware 6.x
• GoKarla Account - Sign up at portal.gokarla.io
• API Credentials - Shop slug and API key from your GoKarla account. See Authentication.

Installation

Option 1: Via Shopware Admin Panel (Recommended)

1. Download the latest KarlaDelivery.zip from GitHub Releases
2. In Shopware admin, navigate to Extensions → My Extensions
3. Click Upload extension and select the downloaded ZIP file
4. Click Install and then Activate
5. Configure your API credentials in the extension settings

For detailed instructions, see Shopware Integration Documentation.

Option 2: Via Composer

composer require gokarla/shopware
bin/console plugin:refresh
bin/console plugin:install --activate KarlaDelivery
bin/console cache:clear

Option 3: Manual Installation via Console

1. Download and extract KarlaDelivery.zip to <shopware-root>/custom/plugins/
2. Run the following commands:

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

Configuration

After installation, configure the extension:

1. Go to Extensions → My Extensions → Karla Delivery → Configure
2. Enter your Shop Slug and API Key from your GoKarla account
3. Configure which order and delivery statuses should trigger synchronization
4. (Optional) Set up sales channel mapping for multi-shop setups
5. Save the configuration

Recommended Settings:

• Order Statuses: Enable "In Progress" and "Completed"
• Delivery Statuses: Enable "Shipped" and "Shipped Partially"

Support

• Documentation: docs.gokarla.io
• Issues: GitHub Issues
• Contact: For additional support, contact your GoKarla account manager

Contributing

We welcome contributions! This is an open-source project under the Apache-2.0 License.

Quality Standards:

• All code must pass make check-all (linting, static analysis, and tests)
• Follow PSR-12 coding standards
• Add tests for new features
• Update documentation as needed

Development Setup

Install dependencies:

composer install

Code Quality

This project follows PSR-12 coding standards and uses modern PHP tooling for quality assurance.

Available Commands:

# Check code style with PHP-CS-Fixer
make lint

# Auto-fix code style issues
make format

# Run static analysis with PHPStan
make analyse

# Run tests with PHPUnit
make test

# Generate code coverage report
make coverage

# Run all quality checks
make check-all

Tooling:

• PHP-CS-Fixer - Fast, modern code formatter
• PHPStan - Static analysis to catch bugs before runtime
• PHPUnit - Comprehensive test suite
• EditorConfig - Consistent formatting across editors

Code Coverage

To generate code coverage reports locally, you need Xdebug installed:

macOS (Homebrew):

# Install with sudo (Homebrew Cellar requires elevated permissions)
sudo pecl install xdebug

Verify installation:

php -m | grep xdebug

Alternative if PECL fails - compile from source:

# Download and compile xdebug
git clone https://github.com/xdebug/xdebug.git
cd xdebug
phpize
./configure
make
sudo make install

# Enable in php.ini
echo "zend_extension=xdebug.so" | sudo tee -a $(php --ini | grep "Loaded Configuration" | sed -e "s|.*:\s*||")

Linux (Ubuntu/Debian):

sudo apt install php8.3-xdebug

Docker/Dockware:

# Xdebug is pre-installed in Dockware containers

After installing Xdebug, run:

make coverage
# Open coverage/html/index.html in your browser

Coverage reports are automatically generated in CI and uploaded to Codecov.

Local Development with Dockware

Start a local Shopware instance:

make dockware-start
make dockware-attach

Access the development shop:

• Admin Panel: http://localhost/admin (credentials: admin / shopware)
• Storefront: http://localhost
• Logs: http://localhost/logs

For detailed development guidelines, see CLAUDE.md.

Historical ERP migrations

In Extensions → My extensions → Karla Delivery → Configuration, select the intended sales channel. Under Historical migration protection:

1. Set Original order date cutoff to the first order timestamp that should remain active. The comparison is strictly before the cutoff; orders exactly at the cutoff are included in normal processing. The datetime control uses the administrator's timezone and stores an ISO timestamp with timezone.
2. Turn on Enable migration protection and save before starting the ERP export. Repeat for each affected sales channel, or configure All sales channels deliberately. Shopware's usual channel overrides and inheritance apply.
3. Test one historical delivery update and one current order. Historical order and delivery writes must produce no Karla order request or trackpage write; current orders retain their existing behavior. Authenticated shipment webhooks for excluded orders return HTTP 200 with reason: migration_protection and do not trigger Shopware Flow Builder. Claim events remain unchanged.
4. Keep protection enabled until all migration writes, importer retries and in-flight shipment events have finished. Disable it only when historical orders will no longer be updated or emit events. Disabling does not replay skipped records, but future writes/events will process normally again.

The cutoff uses the stored order's original orderDateTime, not the delivery's last-modified timestamp. No shop or cutoff is built in; protection is off by default. An enabled setting with a missing/invalid cutoff blocks all order sync and shipment flows in that channel and logs an error. Enter a valid cutoff to restore current-order processing. API-configured cutoffs must be ISO timestamps with an explicit timezone (for example 2026-01-01T00:00:00Z).

This plugin guard does not cancel emails or delayed Flow Builder actions already queued before activation, stop other email integrations, or unregister tracking already sent to Karla. Check those separately if an import has already started. The existing Historical delivery cutoff remains independent and unchanged. No Karla backend update is required for this plugin guard.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Independent brands on one Shopware installation

Use a separate sales channel and Karla shop for each brand. Set the shop slug and API credentials in that sales channel's plugin configuration. Existing salesChannelMapping entries take precedence over the configured shop slug.

Enable webhooks separately in each channel. Channel subscriptions use /api/karla/webhooks/{salesChannelId}/{webhookId} and a dedicated signing secret; a channel callback only dispatches events for orders belonging to that channel. The existing global callback continues to support single-shop installations. Inherited global subscriptions are never reused or deleted by a channel toggle.

For channel subscriptions created before this update, disable and re-enable webhooks in that channel to register the new callback. Verify the correct Karla shop and credentials before doing so. Changing those credentials or the shop mapping requires recreating the subscription against the intended shop.

Before launching a second brand, test one order and fulfillment per channel. Verify each order reaches its own Karla shop, its tracking link opens the right brand, and its webhook triggers the correct language, sender and email template. Confirm both endpoints return successful responses. A code release alone does not verify a merchant's installed plugin version or webhook health.