47 "when": "Never for the subscriber request itself — this is a verified native write surface. Only source fields with nowhere to land (e.g. a custom quantity-wanted field some plugins carry) fall back to a notes/CMS-archive entry, not the request record."
48 }
49 ],
50 "reliability": {
51 "status": "partially-reliable",
52 "flags": []
53 },
54 "pitfalls": [
55 {
56 "code": "requires-collection-enabled-first",
57 "severity": "blocker",
58 "summary": "VERIFIED LIVE 2026-10-27: create answers 428 REQUEST_COLLECTION_DISABLED until Start Collecting Requests (POST .../settings/start-collecting { appId: Wix Stores }) has run; it is the setup step start-back-in-stock-collection, verified by Get Settings (a PUT with an empty body) showing collectingRequests true for the Stores app id. createBackInStockRequest rethrows the 428 with code BACK_IN_STOCK_COLLECTION_DISABLED: a setup failure, not a per-row retry. Collecting also shows the \"Notify When Available\" button on out-of-stock products."
59 },
60 {
61 "code": "requires-product-crosswalk-first",
62 "severity": "blocker",
63 "summary": "catalogReference.catalogItemId must be a real Wix Stores Catalog V3 product/variant id. Sequence this entity strictly after stores/product (and its crosswalk) in the import order; a source product id can never be passed through directly."
64 },
65 {
66 "code": "duplicate-pair-is-not-an-error",
67 "severity": "warning",
68 "summary": "VERIFIED LIVE 2026-10-27: a duplicate (catalogReference, email) while the first request is still RECEIVED answers 409 BACK_IN_STOCK_NOTIFICATION_REQUEST_ALREADY_EXISTS with no id (the docs prose claiming a 200 with the existing request is wrong). Query filters on status only: filters on contactId, email, id, itemUrl and catalogReference.catalogItemId are all refused (400 FILTER_PARSER_VALIDATION). createBackInStockRequest recovers by paging status RECEIVED and matching email + catalogItemId + variantId client-side; no single match leaves the row deferred (back-in-stock-duplicate-unresolved), never an invented id. After a request is NOTIFICATION_SENT, a new create for the same pair succeeds as a new RECEIVED request."
69 },
70 {
71 "code": "creation-does-not-notify",
72 "severity": "info",
73 "summary": "Unlike most bulk-import writes in this domain, creating a request does NOT email the customer — only an actual restock (or the offline Mark As Notification Sent call) does. No disableNotifications-equivalent flag exists or is needed; historical import is safe by default."
74 },
75 {
76 "code": "creates-a-contact",
77 "severity": "warning",
78 "summary": "VERIFIED LIVE 2026-10-27: a request for an email with no contact created a new contact (contactId returned); an email that already had a contact reused it. Back-in-stock volume is CRM contact volume: show the count in the plan before consent."
79 },
80 {
81 "code": "back-in-stock-app-required",
82 "severity": "blocker",
83 "summary": "VERIFIED LIVE 2026-10-27: the settings endpoints answer 401 \"TPA 16be6c71-d061-4f56-8cda-c6aa911d1832 is not installed\" on a Stores site until that app is installed (the install-wix-back-in-stock setup step). Create also needs itemDetails.name and itemDetails.price (400 REQUIRED_FIELD without them)."
84 },
85 {
86 "code": "in-stock-items-accepted",
87 "severity": "info",
88 "summary": "VERIFIED LIVE 2026-10-27: a request for an item that is in stock is accepted (RECEIVED). No stock-based filter is applied: notifications are handled by the site mute."
89 }
90 ],
91 "mappingGuidance": [
92 "Dependencies: stores/product per record (request.catalogReference.catalogItemId). No crm/contact dependency: the request carries only an email, and Wix matches or creates the contact itself (creates-a-contact); the crm/contact upsert matches by email, so the order of the two imports does not matter and a contact task that did not finish never holds the requests.",
94 "Map source product/variation id, after crosswalk, -> request.catalogReference.catalogItemId; always set request.catalogReference.appId to the fixed Wix Stores app id 215238eb-22a5-4c36-9e7b-e7c08025e04e.",
95 "A source variation-level subscription -> request.catalogReference.options.variantId (Catalog V3 option/variant id, post-crosswalk), not a separate entity.",
96 "itemDetails.name and itemDetails.price are required on every create call and are NOT stored fields on the request's own read shape (they only feed the notification template) -- pull them from the already-imported product at write time, not from any source data.",
97 "request.itemUrl should be the live Wix product page URL once known; omit if not yet resolvable rather than guessing.",
98 "Import every source subscription. A row the source already notified (mail-sent) is created and then marked with Mark As Notification Sent (offline, sends nothing): pass notified: true to createBackInStockRequest. A marked request no longer blocks a duplicate create, so a re-run of a record whose request id is known (journal or crosswalk target, including outcome mark-unverified) passes knownRequestId: the request is read and finished, never created again. Unsubscribed rows are not subscriptions and are not imported; record each in the faithfulness ledger so the omission is visible."
120 "note": "fetched 2026-08-19 -- this single page contradicts itself: its intro prose says a duplicate (catalogReference, email) returns the existing request (200), but its own Possible-Errors table lists 409 ALREADY_EXISTS / BACK_IN_STOCK_NOTIFICATION_REQUEST_ALREADY_EXISTS for the identical condition -- see duplicate-pair-is-not-an-error pitfall"
125 "note": "fetched 2026-08-19 -- queryable fields are id, contactId, status, autoNotified, createdDate, itemUrl only; catalogReference.catalogItemId and email are NOT filterable, so the 409 recovery lookup must go through contactId then filter client-side (see duplicate-pair-is-not-an-error pitfall)"