Shopware 6.7 represents a significant evolution in the e-commerce platform's architecture, emphasizing performance, developer experience, and cloud-native extensibility. Central to this evolution is the App System, which has matured into the preferred method for building third-party integrations, SaaS connections, and feature extensions. Unlike traditional plugins, Apps offer a more modular, secure, and scalable approach, decoupling functionality from the core codebase while maintaining deep integration capabilities.

In this guide, we will explore how to build a robust App for Shopware 6.7+, leveraging the latest tooling, manifest structure, and security standards.

Why Apps in Shopware 6.7?

Shopware 6.7 continues to prioritize the separation of concerns. Apps run in isolated processes, communicate via standardized APIs, and utilize OAuth2 for secure authorization. This architecture ensures that your App does not impact core stability, supports horizontal scaling, and aligns with modern DevOps practices. Whether you are building a payment gateway, ERP connector, or admin dashboard enhancement, the App System provides the necessary hooks, events, and UI frameworks to deliver a seamless experience.

Prerequisites and Tooling

Before diving into development, ensure your environment is up to date. Shopware 6.7 requires PHP 8.2+ and relies heavily on the official Shopware CLI.

  1. Install Shopware CLI: 
    composer global require shopware/cli
  2. Local Environment: You need a running Shopware instance (local or cloud) with SSH access.
  3. Tunneling Solution: For local development, you'll need to expose your App's webhook endpoints. The CLI includes a tunnel feature, or you can use tools like ngrok or cloudflared.

Step 1: Scaffolding Your App Structure

Shopware 6.7 Apps follow a strict directory structure defined by the platform for validation and loading. Generate a skeleton using the CLI to ensure compliance with 6.7 standards:

sw app generate my-awesome-app
cd my-awesome-app

The generator creates the essential files:

  • app/app.json: The manifest defining metadata, scopes, and endpoints.
  • src/: Contains your PHP controllers, services, and logic.
  • administration/: (Optional) Vue components for admin UI integration.
  • test/: PHPUnit tests for your app logic.

Step 2: Mastering the App Manifest (app.json)

The manifest is the heart of your App. In Shopware 6.7, validation has become stricter, and new fields support advanced capabilities like OpenTelemetry tracing integration and granular admin UI definitions.

Key sections include:

  • App Metadata: Name, version, and author information.
  • Capabilities: These define what your App can do without requiring manual installation approval for every feature. In 6.7, you might register capabilities like purchase or custom-entity-write to enable seamless interactions with Storefront or Checkout flows.
  • Endpoints: Maps external URLs to internal controllers. The CLI helps validate these routes against your PHP implementation.

Example snippet of a robust app.json:

{
  "app": {
    "name": "MyAwesomeApp",
    "label": "My Awesome App",
    "description": "Seamless integration for Shopware 6.7 with advanced analytics.",
    "version": "1.0.0",
    "icon": "src/Resources/public/img/icon.svg",
    "capabilities": [
      "purchase",
      "storefront:cart:checkout"
    ],
    "endpoints": {
      "webhook": "https://your-domain.com/api/app/webhook",
      "callback": "https://your-domain.com/api/app/callback"
    },
    "administration": {
      "routes": [
        {
          "path": "my-awesome-app.dashboard",
          "component": "my-awesome-app-dashboard",
          "name": "MyAwesomeAppDashboard",
          "parent": "sw-admin"
        }
      ]
    }
  }
}

Note: In Shopware 6.7, ensure that your administration.routes correctly reference component names defined in your JS/Vue build process. The platform now supports better type-checking for these definitions via the CLI.

Step 3: Developing the Backend Logic

Your App's backend must handle HTTP requests securely. Shopware 6.7 enforces OAuth2/App Access Token validation for all incoming API calls from the storefront or admin context.

Handling Webhooks

When a Storefront action triggers a webhook, Shopware sends a request to your defined endpoint. Your controller must validate the App's access token and process the payload efficiently.

# src/Controller/WebhookController.php
<?php declare(strict_types=1);

namespace MyAwesomeApp\Controller;

use Psr\Log\LoggerInterface;
use Shopware\Core\Framework\Routing\Annotation\RouteScope;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;
use Shopware\AppFramework\Http\AppContextFactory;
use Shopware\AppFramework\Entity\SalesChannelRepository;

#[Route(defaults: ['_auth' => 'app'])]
class WebhookController extends AbstractController
{
    public function __construct(
        private readonly AppContextFactory $contextFactory,
        private readonly SalesChannelRepository $salesChannelRepo
    ) {}

    #[Route('/api/app/webhook', name: 'app-my-awesome-app-webhook', methods: ['POST'])]
    public function webhook(Request $request): Response
    {
        // Validate the request signature and token
        if (!$this->validateRequest($request)) {
            return new Response('Unauthorized', 401);
        }

        $payload = json_decode($request->getContent(), true);
        
        // Use AppContextFactory to get a valid context for database operations
        $context = $this->contextFactory->createAppContext();

        // Example: Listen for cart checkout events and push data to your SaaS
        if ($payload['eventName'] === 'cart.checkout') {
            $this->syncToSaaS($payload, $context);
        }

        return new Response('Received', 200);
    }

    // ... Implement validateRequest, syncToSaaS, etc.
}

Shopware 6.7 Tip: Utilize the AppContextFactory to ensure your app has the correct permissions for CRUD operations. Avoid using legacy Plugin services; instead, leverage dependency injection and Symfony's service container.

Step 4: Admin UI Integration

Enhancing the Shopware Admin is straightforward in 6.7. Create Vue components in administration/src/components/. The App System injects these into the SPA without a page reload.

  1. Define the route in app.json.
  2. Create the component using the latest Storefront API standards compatible with 6.7.
  3. Register the component in administration/src/main.js:
const MyAwesomeAppDashboard = () => import('./components/dashboard/index');

Shopware.Component.register('my-awesome-app-dashboard', MyAwesomeAppDashboard);

Your widget can now access data via the Store API (sw-api) or custom app endpoints. Shopware 6.7 improves frontend performance by lazy-loading these components automatically when the route is accessed.

Step 5: Development Workflow and Debugging

The Shopware CLI streamlines the loop between code changes and activation.

# Start development server with auto-tunneling
sw app start --port=8080

# Validate manifest and structure
sw app validate

# Upload directly to your shop for testing
sw app upload ./my-awesome-app.tar.gz http://your-shop.local admin password

Debugging Tips:

  • Check the var/log/shopware.log for App-related errors.
  • Use the CLI command sw app logs to tail logs from your App's server during development.
  • Ensure your tunnel URL matches exactly what is in app.json. Mismatches are a common cause of activation failures in 6.7 due to stricter SSL and domain validation.

Best Practices for Shopware 6.7 Apps

  1. Idempotency: Webhooks may be retried. Ensure your logic can handle duplicate events safely.
  2. Security: Never store secrets in code. Use environment variables or the Shopware secret vault if supported. Validate all inputs rigorously.
  3. Performance: Apps should be lightweight. Avoid heavy dependencies that increase startup time. Use async processing for non-critical tasks.
  4. Manifest Validation: Run sw app validate before every release. Shopware 6.7's validation catches deprecations early, saving deployment headaches.
  5. Capabilities Strategy: Use capabilities wisely. They allow your App to request permissions dynamically, but over-reliance can lead to approval delays in the Store.

Conclusion

Building a Shopware 6.7 App requires embracing the platform's modernization. By leveraging the App System, you gain access to a secure, scalable, and developer-friendly ecosystem. The combination of strict manifest definitions, OAuth2 security, enhanced CLI tooling, and robust admin integration empowers developers to create world-class extensions that enhance the Shopware experience without compromising stability.

Start by generating your app structure, define clear capabilities, implement secure webhook handlers, and polish your admin UI. With Shopware 6.7, the bar for quality is high, but the tools are equally powerful. Happy coding!