Shopware 6.7 represents a significant leap in headless commerce capabilities, offering developers a robust, flexible REST API designed for high-performance custom integrations. Whether you are connecting an ERP system, synchronizing inventory across multiple channels, or building a bespoke PIM solution, mastering the Shopware 6 API is essential.

In this guide, we will explore how to architect a reliable integration using Shopware 6.7 standards, focusing on authentication, data retrieval, and modern best practices introduced in recent releases.

Understanding Shopware 6.7 Integrations

The concept of "Integrations" in Shopware has evolved to support secure server-to-server communication. In version 6.7, the Integration system provides granular control over API access. Instead of relying on admin users with full privileges, you create dedicated integration entities scoped to specific needs.

Creating and Configuring an Integration

Navigate to Settings > Integrations in your Administration panel. Click "Create" to generate a new integration. You must define a name and select the API scope. Shopware 6.7 allows you to toggle permissions per entity (e.g., product, customer, order). This principle of least privilege ensures security; if a breach occurs, the impact is limited to the granted scopes.

Once created, the system generates an Access Key. Unlike legacy session-based auth, Access Keys are designed for long-lived integrations and are the recommended method for v6.7+ connections. Each integration key is bound to the specific store context where it was created, ensuring clear separation in multi-storefront environments.

Authentication in Shopware 6.7

The API supports Access Key authentication via HTTP headers or Basic Auth. In a production environment, using the sw-access-key header is preferred to avoid exposing credentials in URL query parameters or log files associated with Basic Auth schemes. This method ensures that your credentials are not cached by proxies or browsers unintentionally.

GET /api/v1/product HTTP/1.1
Host: store.example.com
sw-access-key: YOUR_ACCESS_KEY_HERE
Content-Type: application/json
Accept: application/json

Fetching Data with Precision

One of the most powerful features in the Shopware 6 API is its filtering and serialization capabilities. You rarely need to fetch the entire product entity. By utilizing the includes parameter, you can request only the associations and fields your integration requires. This drastically reduces payload size and memory consumption on the server side, a critical optimization for large catalogs in v6.7.

Code Example: Fetching Products with Includes

Below is a PHP example using Guzzle HTTP client, compatible with Shopware 6.7. This snippet fetches active products, requesting only the ID, name, price, and related media associations. Note how the filter structure uses JSON encoding for complex queries.

use GuzzleHttp\Client;

$endpoint = 'https://your-store.com/api/v1/product';
$accessKey = 'YOUR_ACCESS_KEY_HERE';

$client = new Client(['headers' => ['sw-access-key' => $accessKey]]);

$response = $client->get($endpoint, [
    'query' => [
        'includes' => [
            'product' => ['id', 'name', 'price'],
            'media'   => ['url']
        ],
        'filter' => [
            'active' => true
        ]
    ]
]);

$products = json_decode($response->getBody(), true);

Note on v6.7 Stability: The API structure in 6.7 maintains backward compatibility with the api/v1 namespace while introducing stricter validation. Ensure your client handles JSON-LD structures correctly, as Shopware returns data conforming to OpenAPI specifications. The response also includes pagination metadata; always check for total and links to handle large datasets efficiently.

Writing Data and Batch Operations

Integrations often require bidirectional synchronization. When updating or creating records, use PATCH for partial updates to avoid overwriting immutable fields like createdAt, and POST for creation. Ensure prices are sent as an array of currency prices (e.g., [{"currencyId": "b7d2554b0ce84bedcd89d99360699cdb", "net": 10, "gross": 12, "linked": false}]) to comply with multi-currency requirements common in v6.7.

For high-volume scenarios, direct individual calls can hit rate limits and incur network overhead. Shopware 6 excels at batch processing via the /api/v1/batch endpoint. This allows you to dispatch up to 50 requests in a single HTTP call, optimizing throughput for bulk updates or imports.

Code Example: Batch Update Stock

$batchPayload = [
    'update' => [
        'product' => [
            ['id' => 'uuid-product-1', 'data' => ['stock' => 50]],
            ['id' => 'uuid-product-2', 'data' => ['stock' => 75]]
        ]
    ]
];

$response = $client->post('/api/v1/batch', [
    'json' => $batchPayload,
    'headers' => ['sw-access-key' => $accessKey]
]);

// Process response which contains results for each request in the batch
$results = json_decode($response->getBody(), true);

Best Practices for Production Integrations

  1. Error Handling: Always inspect response codes. Shopware returns specific error keys (e.g., PRODUCT__INVALID_PRICE) that help debug payload issues instantly. Wrap HTTP calls in try-catch blocks to handle GuzzleHttp\Exception\RequestException and manage connection retries gracefully.
  2. Rate Limiting: The API enforces rate limits based on server resources. Monitor the X-RateLimit-Remaining header in responses. Implement exponential backoff if you receive HTTP 429 errors to prevent blocking your integration flow.
  3. Pagination Strategy: For large datasets, never attempt to load all records at once. Use cursor-based pagination where available for superior performance on offset-heavy tables. The API response includes meta with total counts and links.next.
  4. Multi-Storefront Contexts: In v6.7, integrations are context-aware. If you manage multiple storefronts, ensure your integration keys are created within the correct store scope. The API enforces these boundaries automatically; attempting to access resources from a different store will result in authorization errors.
  5. Security Hygiene: Rotate access keys periodically via the Admin panel. Store secrets in environment variables or secret managers, never hardcoding them in source code. Validate all incoming data before sending it to the API to prevent injection issues.

Conclusion

Building a custom integration with Shopware 6.7 leverages a mature, RESTful API that supports granular security and high-performance data handling. By utilizing Access Keys, efficient serialization via includes, and batch operations, you can build integrations that are both secure and scalable. As Shopware continues its release train, the core API patterns established in 6.7 provide a stable foundation for headless commerce architectures, ensuring your custom solutions remain compatible and performant for years to come.

Start by defining your scope, create your integration, and begin synchronizing your data with confidence.