Shopware 6.5 Category API schema change breaks nested category import for third-party adapter

Answer first

Rebuild the tree locally from a flat list keyed by parentId and write categories with the Sync API using parentId inline. Do not rely on a nested children array in the response. Ordering is set per parent via position in the write payload; a separate sorting pass is only needed if your test shows order is lost. Cache warmup is not strictly required for storefront consistency, targeted cache invalidation is.

What is confirmed vs likely

Confirmed behavior in Shopware 6.x: The category entity is a self-referencing tree. Each record stores parentId, level and path. The DAL can hydrate children on demand, but repository reads return flat entities. Bulk writes are recommended via POST /api/_action/sync with upsert operations on the category repository.

Unverified in this report: Shopware 6.5 did not universally replace nested children with a flattened tree in the Admin API. The Store API navigation endpoint has always returned a tree shape, while Admin API repository queries return flat entities with associations. The claim that categoryPosition is deprecated in favor of a dedicated sorting endpoint cannot be confirmed from model knowledge and is version-sensitive. Treat it as unverified until checked against your exact 6.5.x changelog.

Steps for this case

1. Identify the API surface used. Check whether the importer calls Admin API /api/category or Store API /store-api/navigation. The fix differs.
2. Fetch flat and rebuild locally. If you need to read existing categories, query with Criteria and include parentId. Build an id -> node map and a parentId -> children map in memory, then recurse locally instead of expecting children in the response.
3. Write with Sync API. Use POST /api/_action/sync with upsert actions for category. Include parentId inline for each node. Example shape:

{
  "write-category": [
    {"action": "upsert", "entity": "category", "payload": [{
      "id": "...",
      "parentId": "...",
      "name": "...",
      "position": 0
    }]}
  ]
}

Write parents before children or let the sync resolve by id. Position is set per parent group.

1. Ordering. Test a small parent with two children with explicit position values in the sync payload. Verify in the database and storefront. If order is not preserved, add a second pass that updates position only for that parent. Do not assume a separate sorting endpoint exists without verifying your 6.5.x release notes.
2. Cache consistency. After bulk writes, invalidate storefront/category caches rather than relying on bin/console cache:warmup. Warmup rebuilds container cache, not HTTP or navigation caches. Typical steps: clear the Shopware cache tags for category and navigation, then warm the navigation tree. Compare storefront category counts to SELECT count(*) FROM category and grouping by parent_id.

One missing diagnostic that changes the recommendation

Confirm which endpoint the importer currently reads from: Admin API category repository vs Store API navigation. If it is Store API, you are already receiving a tree and the parser change is expected. If it is Admin API, the response was already flat and the breakage is likely due to association hydration changes or a client library upgrade, not a schema flattening.