Inventory Item

1{
2  "schemaVersion": 1,
3  "domain": "stores",
4  "entity": "inventory-item",
5  "displayName": "Stores Inventory Item",
6  "target": {
7    "classification": "native",
8    "nativeEntity": "Stores Inventory Item",
9    "verifiedFqdn": null,
10    "idPolicy": "server-assigned",
11    "crosswalkRequired": true
12  },
13  "sourceAliases": [
14    { "sourceSystem": "woocommerce", "sourceEntity": "product_variation_inventory", "routes": ["/wc/v3/products", "/wc/v3/products/{productId}/variations"], "confidence": "medium" },
15    { "sourceSystem": "wix", "sourceEntity": "inventoryItem", "routes": ["Stores Inventory APIs"], "confidence": "high" }
16  ],
17  "preferredWrite": {
18    "surface": "Stores Inventory V3",
19    "endpoint": "POST /stores/v3/inventory-items",
20    "writerId": "createInventoryItem",
21    "verification": "unverified",
22    "importSafe": true,
23    "bulk": false
24  },
25  "fallbacks": [
26    { "classification": "cms", "when": "Use for source stock history or multi-location detail not represented by the selected target inventory plan." }
27  ],
28  "reliability": { "status": "partially-reliable", "flags": [] },
29  "pitfalls": [
30    { "code": "product-first", "severity": "blocker", "summary": "Inventory requires target product and variant IDs." },
31    { "code": "bis-side-effects", "severity": "warning", "summary": "Avoid stock transitions that trigger Back in Stock notifications on live stores." }
32  ],
33  "mappingGuidance": ["Create products first, then create or update inventory per variant."],
34  "setupRequirements": ["SCOPE.STORES.INVENTORY_ITEM_WRITE"],
35  "evidence": [
36    { "type": "repo-research", "path": "research/import-api-suitability/stores-catalog-inventory.md" }
37  ]
38}