Category

1{
2  "schemaVersion": 1,
3  "domain": "stores",
4  "entity": "category",
5  "displayName": "Stores Category",
6  "capability": "commerce.catalog-category",
7  "target": {
8    "classification": "native",
9    "nativeEntity": "Stores Category",
10    "verifiedFqdn": null,
11    "idPolicy": "server-assigned",
12    "crosswalkRequired": true
13  },
14  "dependsOn": [],
15  "sourceAliases": [
16    {
17      "sourceSystem": "woocommerce",
18      "sourceEntity": "product_category",
19      "routes": [
20        "/wc/v3/products/categories"
21      ],
22      "confidence": "high"
23    },
24    {
25      "sourceSystem": "wix",
26      "sourceEntity": "storesCategory",
27      "routes": [
28        "Catalog V3 Categories",
29        "V1 collections"
30      ],
31      "confidence": "high"
32    }
33  ],
34  "preferredWrite": {
35    "surface": "Categories",
36    "endpoint": "POST /categories/v1/categories",
37    "writerId": "createStoresCategory",
38    "verification": "verified-live",
39    "importSafe": true,
40    "bulk": false
41  },
42  "fallbacks": [
43    {
44      "classification": "cms",
45      "when": "Use only for source taxonomy metadata or hierarchy details not represented by Stores categories."
46    }
47  ],
48  "reliability": {
49    "status": "reliable",
50    "flags": []
51  },
52  "pitfalls": [
53    {
54      "code": "tree-reference-top-level",
55      "severity": "blocker",
56      "summary": "Pass Stores treeReference as a top-level sibling of category."
57    }
58  ],
59  "hierarchy": {
60    "maxNestingDepth": 5,
61    "source": "user-confirmed domain knowledge",
62    "confirmedBy": "user (Wix domain expert), 2026-08-12",
63    "liveVerified": false,
64    "note": "Not yet independently live-verified by this pipeline (e.g. no throwaway multi-level treeReference probe has confirmed this on a live site). Recorded as fact per user statement so future migrations do not need to re-ask or re-test this. If a future run needs live confirmation, verify with a small test chain and update liveVerified/evidence here rather than re-opening the question as unknown."
65  },
66  "mappingGuidance": [
67    "Preserve hierarchy where the target category tree supports it (up to 5 levels of nesting per Wix Stores category tree); create before products.",
68    "If a source category tree exceeds 5 levels, re-parent nodes deeper than level 5 up to their level-5 ancestor and record the flattening as a documented faithfulness-ledger loss -- do not silently drop or guess."
69  ],
70  "setupRequirements": [
71    "Wix Stores app"
72  ],
73  "evidence": [
74    {
75      "type": "wix-docs",
76      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/category-object",
77      "note": "object page (docs-survey sweep 2026-08-11)"
78    }
79    
80  ]
81}