47 "when": "Use for source stock history or multi-location detail not represented by the selected target inventory plan."
48 }
49 ],
50 "reliability": {
51 "status": "reliable",
52 "flags": []
53 },
54 "pitfalls": [
55 {
56 "code": "product-first",
57 "severity": "blocker",
58 "summary": "Inventory requires target product and variant IDs."
59 },
60 {
61 "code": "bis-side-effects",
62 "severity": "info",
63 "summary": "Avoid stock transitions that trigger Back in Stock notifications on live stores. Covered by site mute: when getSiteMuteState reads muted:true, this is not a reason to block, skip, delay or warn about the entity."
64 },
65 {
66 "code": "tracking-oneof",
67 "severity": "blocker",
68 "summary": "inStock and quantity are mutually exclusive. trackQuantity and availabilityStatus are read-only; do not send them to select tracking mode."
69 },
70 {
71 "code": "inventory-completion-independent",
72 "severity": "blocker",
73 "summary": "A product receipt is not inventory verification. Preserve inventory gaps, failed writes and mismatched read-backs in a separate partial checkpoint and report."
74 },
75 {
76 "code": "existing-preorder-policy",
77 "severity": "blocker",
78 "summary": "Reconciliation refuses existing enabled preorder settings instead of silently changing the merchant policy. Resolve the policy before updating stock."
79 },
80 {
81 "code": "catalog-inventory-disagreement",
82 "severity": "blocker",
83 "summary": "Default-location Inventory and Catalog variant availability are separate reads. An inventory item can be correct while Catalog still marks the same variant unavailable. Require both to agree; bounded read retries may recover propagation, but never toggle stock to repair a disagreement."
84 }
85 ],
86 "mappingGuidance": [
87 "Use stores-inventory.js reconcileInventory with resolved product/variant IDs and an explicit expectedCount including source gaps. Reads are scoped to one resolved Stores location. Query before create; compare before accepting existing inventory; update with current id/revision and verify by read-back.",
88 "Write exactly one tracking field: inStock (boolean) or quantity (integer 0–99999 for creation). trackQuantity is read-only and derived. Verify its value, exact stock value, identity and availabilityStatus.",
89 "Initial bulk product creation can include variantsInfo.variants[].inventoryItem in the default location. Always verify inventory independently of product success; recover stock using existing product/variant IDs.",
90 "Unknown source stock is a named mapping gap, never implicit availability. Backorders, preorders and shared stock allocation require explicit policy decisions. Do not duplicate pooled quantity across variants.",
91 "Bulk results require originalIndex and complete accounting. A 409, partial bulk response, stale revision or unreadable write remains failed/unverified until a later read confirms the intended value. Use absolute updates, not increment/decrement operations for reruns.",
92 "For default-location rows, reconcileInventory also reads each distinct Catalog product (at most four concurrent reads), matches exact variant IDs and verifies inventoryStatus.inStock and disabled preorder. Missing or conflicting Catalog state remains unverified even on no-write reruns. Non-default-location rows explicitly record Catalog verification as not applicable."
93 ],
94 "setupRequirements": [
95 "Read Stores Locations in v3 catalog",
96 "Read inventory in v3 catalog",
97 "Inventory write in v3 catalog (create and update)",
98 "Resolve one Stores location; verify read, create, update and read-back using the actual import token and approved canary; retain notification protection",
99 "Read products in v3 catalog, including hidden products and variants (Product v3 read admin), for Catalog consistency verification"
110 "note": "Revisioned bulk update; live create/read/update/reconcile and inline stock verified with synthetic hidden products. Probe cleanup succeeded; no preorder or multi-location allocation claim."
115 "note": "Default-location availability is checked against the exact Catalog variant as well as the inventory item; a persistent disagreement has been observed in read-only verification."