Automating product data synchronization is one of the most frequent integration requirements for modern e-commerce operations. Whether you are mirroring an ERP catalog, migrating from a legacy platform, or maintaining multi-channel inventory, programmatically feeding products into your store eliminates manual entry errors and accelerates time-to-market. While Shopware’s built-in Import/Export module handles CSV-based workflows beautifully, the Administration API provides granular control, real-time validation, and seamless bidirectional sync capabilities. With Shopware 6.7 arriving, several architectural refinements have made API-driven imports more predictable, secure, and developer-friendly. This guide walks you through the exact steps to import products via the API, emphasizing what has changed in 6.7 and how to structure your integration for production reliability.

Authentication & Permissions

Before sending any entity data, your client must authenticate successfully. Shopware 6 uses a key-based authentication model by default. Navigate to Settings → Users & Security → Access Keys in the Administration panel and generate a new key pair with at least product:read and product:write permissions. Assign it to a service account that does not require two-factor authentication for API calls.

Pass the credentials as HTTP headers on every request:

sw-access-key: <your-access-key>
sw-secret-key: <your-secret-key>

Alternatively, if your infrastructure mandates OAuth2 bearer tokens, exchange these keys at /api/v3/oauth/token and attach the resulting access_token to the Authorization: Bearer <token> header. Remember that access tokens expire after 720 seconds by default, so implement token refresh logic in long-running workers.

Understanding the Payload Structure

The core endpoint for product creation is POST /api/v3/product. In Shopware 6.7, the Administration API enforces stricter data transfer object (DTO) validation and explicit relationship mapping. A valid request must wrap products inside a top-level products array. Unlike previous versions where tax rules or main categories defaulted silently, 6.7 requires explicit references to avoid immediate validation failure.

Here is a production-ready example:

{
  "products": [
    {
      "id": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
      "name": "Mesh Ergonomic Office Chair",
      "productNumber": "CHAIR-ERGO-2024",
      "status": 1,
      "stock": 85,
      "description": "<p>Advanced lumbar support with breathable fabric and adjustable armrests...</p>",
      "price": [
        {
          "currencyId": "b7d2554b0ce84addcd296ebe6c173ab6",
          "gross": 249.99,
          "net": 210.08
        }
      ],
      "tax": { "id": "f94e7a5c-8d3b-4e2a-9c1d-0b8e7f6a5d4c" },
      "categories": [
        { "id": "c1a2t3e4g5o6r7y8i9d0", "name": "Office Furniture" }
      ],
      "manufacturer": { "id": "m1a2n3u4f5a6c7t8u9r0e1r2i3d4" },
      "visibilities": [
        { "salesChannelId": "s1a2l3e4s5c6h7a8n9n0e1l2i3d4", "priority": 1 }
      ]
    }
  ]
}

Notice that price expects an array of currency objects. If your store uses multi-currency configuration, include every active currency ISO code required by the target sales channel. Media references should be passed as arrays of pre-uploaded asset IDs rather than inline base64 strings, which Shopware 6.7 deprecates for large payloads.

Executing & Handling Responses

Send a POST request to your store domain with the headers and JSON body. A successful creation returns HTTP 201 Created along with the persisted entity data inside a data.products[0] wrapper. Always inspect the meta object for operation metadata, including timestamps and indexing status.

Validation errors return 422 Unprocessable Entity. The response contains an errors array with structured messages like MISSING_FIELD, DUPLICATE_PRODUCT_NUMBER, or INVALID_CURRENCY_ID. Implement retry logic that maps these codes to corrective actions: update the payload, skip invalid SKUs, or alert your data pipeline. Never silently ignore 4xx/5xx responses; log them and queue failed rows for manual review.

Optimizing for Bulk Imports

While the API accepts multiple products per request, Shopware processes them sequentially to maintain database transactional integrity. For high-volume imports (hundreds or thousands of SKUs), chunk your payloads to 50–100 products per request. This prevents PHP timeout limits and reduces memory consumption during index rebuilding.

For truly asynchronous processing, consider leveraging Shopware’s import/export service endpoints (POST /api/_action/import/export) or pairing the API with a message queue (RabbitMQ/Redis) to decouple sync operations from HTTP request lifecycles. Implement idempotency keys in your integration layer to safely retry failed requests without creating duplicate SKUs.

Shopware 6.7 Changes That Impact Imports

Several updates in 6.7 directly affect how you design product sync logic:

  1. Stricter Validation Rules: productNumber must be globally unique across all channels. Attempting to import a duplicate now throws an immediate validation error instead of falling back silently.
  2. Explicit Currency Mapping: Prices no longer auto-convert using the default store currency. Every price entry requires a valid currencyId that matches your sales channel configuration.
  3. Media Upload Workflow: Base64 embedding is deprecated. Use /api/v3/media for asynchronous uploads, retrieve the resulting asset ID, and attach it via the media array in your product payload.
  4. Indexing Behavior: Every product write triggers immediate search index updates. During massive imports, pause real-time indexing with sw:feature:indexing-disabled, run your sync, then execute bin/console sw:indexing:restart-indexing to rebuild efficiently.
  5. Security Hardening: Cross-origin request policies are stricter. Ensure your CORS configuration allows the origin making API requests, and validate that access keys are scoped exclusively to integration needs.

Conclusion

Importing products into Shopware 6 via API is now more deterministic and performant than ever. By respecting 6.7’s explicit validation rules, chunking payloads appropriately, handling media asynchronously, and implementing idempotent retry logic, you can build robust synchronization pipelines that scale across thousands of SKUs. Always test against a staging instance first, monitor response codes closely, and align your mapping logic with Shopware’s multi-channel architecture. With these practices in place, your product data will flow reliably into the platform, ready to power conversions without manual overhead.