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  "sameTaskReferenceFields": {
16    "stores/category": [
17      "parentCategory.id"
18    ]
19  },
20  "sourceAliases": [
21    {
22      "sourceSystem": "woocommerce",
23      "sourceEntity": "product_category",
24      "routes": [
25        "/wc/v3/products/categories"
26      ],
27      "confidence": "high"
28    },
29    {
30      "sourceSystem": "wix",
31      "sourceEntity": "storesCategory",
32      "routes": [
33        "Catalog V3 Categories",
34        "V1 collections"
35      ],
36      "confidence": "high"
37    }
38  ],
39  "preferredWrite": {
40    "surface": "Categories",
41    "endpoint": "POST /categories/v1/categories",
42    "writerId": "createStoresCategory",
43    "verification": "verified-live",
44    "importSafe": true,
45    "bulk": false
46  },
47  "fallbacks": [
48    {
49      "classification": "cms",
50      "when": "Use only for source taxonomy metadata or hierarchy details not represented by Stores categories."
51    }
52  ],
53  "reliability": {
54    "status": "reliable",
55    "flags": []
56  },
57  "pitfalls": [
58    {
59      "code": "tree-reference-top-level",
60      "severity": "blocker",
61      "summary": "Pass Stores treeReference as a top-level sibling of category."
62    }
63  ],
64  "hierarchy": {
65    "maxNestingDepth": 5,
66    "source": "product domain knowledge",
67    "confirmedBy": null,
68    "liveVerified": false,
69    "note": "Not yet independently live-verified. If live confirmation is required, verify with a small multi-level treeReference test chain and update liveVerified/evidence."
70  },
71  "mappingGuidance": [
72    "Preserve hierarchy where the target category tree supports it (up to 5 levels of nesting per Wix Stores category tree); create before products.",
73    "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.",
74    "Category images take the same one-url, permanent-ceiling path as product media: resolve the source reference to its original, maximum-resolution candidate instead of reading a single named field, and percent-encode the url before sending it."
75  ],
76  "setupRequirements": [
77    "Wix Stores app"
78  ],
79  "evidence": [
80    {
81      "type": "wix-docs",
82      "url": "https://dev.wix.com/docs/api-reference/business-solutions/stores/catalog-v3/categories/category-object",
83      "note": "object page (docs-survey sweep 2026-08-11)"
84    }
85  ]
86}