23 "note": "Same source data shipping-build.js's classifyMethod already classifies for delivery-profile.json's deliveryCarrier.backupRate -- a 'carrier' classification (flat_rate/free_shipping/local_pickup) produces BOTH a DeliveryCarrier.backupRate AND a ShippingOption from the same classified method; they are not alternatives."
24 }
25 ],
26 "preferredWrite": {
27 "surface": "Shipping Options",
28 "endpoint": "POST /ecom/v1/shipping-options",
29 "writerId": "createShippingOption",
30 "verification": "verified-live",
31 "importSafe": true,
32 "bulk": false,
33 "decision": "VERIFIED LIVE 2026-08-15 against the reference store: created two ShippingOptions (Europe 'Flat rate' $8, Israel 'Free shipping' $0) matching the DeliveryCarrier.backupRate already set for those regions, then re-verified via listDeliveryCarriers that the dashboard's own rate table (dashboardTables[].rows[]) picked up a real row for both regions where it previously showed none."
40 "summary": "CRITICAL, LIVE-DISCOVERED 2026-08-15 (not documented on any Delivery Profile/Delivery Carrier doc page -- found only via dev.wix.com's 'Fix Shipping Coverage Gaps' skill article, a separate doc tree from shipping-delivery/delivery-profiles/*): DeliveryCarrier.backupRate does NOT create a ShippingOption, and does NOT clear Wix's own 'This region is missing rates. Add them so customers can complete checkout.' dashboard warning. VERIFIED on the reference store: 'Europe'/'Israel' (created by this pipeline via addDeliveryRegion + addDeliveryCarrier with a correctly-shaped, active backupRate) still showed the warning and had ZERO linked ShippingOptions, while 'Domestic'/'International' (Wix's own auto-created defaults, never touched by this pipeline) each already had a real ShippingOption. A region migration that only calls addDeliveryCarrier is INCOMPLETE -- it appears fully successful (the write returns 200, the read-back matches exactly what was sent) while silently leaving the region non-functional at checkout. Always create a matching ShippingOption (via createShippingOption) for every DeliveryRegion this pipeline creates, from the SAME classified method used for that region's DeliveryCarrier.backupRate -- see shipping-build.js's buildShippingOptionInput."
45 "summary": "Create Shipping Option takes `deliveryRegionId` (singular, required) on the request; the response also echoes a `deliveryRegionIds` (plural) array which was empty/unused in the reference store's real response even though the singular field was set -- don't rely on the plural field being populated. dev.wix.com's own 'Fix Shipping Coverage Gaps' skill article calls this out explicitly as a live error source (`deliveryRegionId is not a valid GUID` when the plural field is used by mistake)."
50 "summary": "`estimatedDeliveryTime` is not enforced by the create call itself, but Wix's own shipping-setup guidance treats a blank value as a defect to avoid ('Always set estimatedDeliveryTime -- never leave it empty'). shipping-build.js's buildShippingOptionInput defaults it to '5-7 business days' when the caller doesn't override; WooCommerce has no equivalent field to source a real value from."
55 "summary": "A WooCommerce zone can have multiple carrier-classified methods (e.g. both flat_rate and free_shipping enabled with different conditions); each becomes its own ShippingOption against the same deliveryRegionId, mirroring how each becomes its own DeliveryCarrier entry -- never collapse multiple methods into one option."
56 }
57 ],
58 "mappingGuidance": [
59 "For every WooCommerce shipping-zone method that shipping-build.js's classifyMethod resolves to kind:'carrier', create BOTH a DeliveryCarrier (backupRate, on the delivery profile) AND a ShippingOption (rates[], standalone resource keyed by deliveryRegionId) from the same classified result -- shipping-build.js's buildDeliveryCarrierInput and buildShippingOptionInput. Creating only the former leaves the region looking fully configured via the API (and even via a plain Query Delivery Profiles read-back) while Wix's own checkout and dashboard still treat it as missing rates.",
60 "amount is a plain decimal string ('8', '0'), same convention as backupRate.amount -- no separate currency/format handling needed.",
61 "conditions[] supports tiered/threshold rates (e.g. BY_TOTAL_PRICE >= X for a free-shipping threshold) but WooCommerce's free_shipping requires/min_amount condition is already flagged as a lost-condition gap at the DeliveryCarrier level (delivery-profile.json's free-shipping-condition-lost pitfall) -- do not also attempt to re-derive a conditions[] entry from that same WooCommerce field without live-verifying the mapping first; ship an unconditional rates[] entry (conditions: []) to match what this pipeline actually verified live."
62 ],
63 "setupRequirements": [],
64 "objectPageException": "The standard API reference menu (dev.wix.com/docs/api-reference/business-solutions/e-commerce/shipping-delivery, checked 2026-08-15) has exactly one subsection, 'Delivery Profiles' -- no 'Shipping Options' subsection and no dedicated ShippingOption '…-object' page exist anywhere in that tree. The entire resource is undocumented there; the only place it's described at all is the 'Shipping: API Reference' skills article (a distilled, AI-agent-oriented reference in a completely separate doc tree, business-solutions/e-commerce/skills/) plus its sibling 'Fix Shipping Coverage Gaps' article. The full field shape is sourced from those two pages' request/response examples instead.",
69 "note": "the article that surfaced ShippingOption's existence and its role in clearing a checkout coverage gap; not linked from or mentioned on any shipping-delivery/delivery-profiles/* page"
74 "note": "full Query/Create/Get/Update/Delete Shipping Option + Add/Remove Delivery Region (on a shipping option) schema and the singular-vs-plural deliveryRegionId gotcha, confirmed 2026-08-15"
75 },
76 {
77 "type": "live-verification",
78 "path": "migrations/reference-run (2026-08-15): Query Shipping Options showed 'Domestic'/'International' (Wix auto-created defaults) each with a real ShippingOption, and 'Europe'/'Israel' (this pipeline's own prior live migration) with none despite a correctly-shaped, active DeliveryCarrier.backupRate on both. Created two real ShippingOptions matching the existing backupRate values, then re-verified via List Delivery Carriers (dashboardTables) that both regions now show an active rate row identical in shape to the two pre-existing defaults."