@wix/agent-skills 1.33.0 → 1.34.0

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order.json

@@ -3,6 +3,7 @@
   "domain": "ecom",
   "entity": "order",
   "displayName": "eCommerce Order",
+  "capability": "commerce.orders",
   "target": {
     "classification": "native-plus-cms",
     "nativeEntity": "eCommerce Order",
@@ -10,19 +11,51 @@
     "idPolicy": "server-assigned",
     "crosswalkRequired": true
   },
+  "dependsOn": [
+    "crm/contact",
+    "stores/product",
+    "gift-cards/gift-card-product",
+    "stores/coupon",
+    "gift-cards/gift-card",
+    "tax/tax-group",
+    "ecom/shipping-option",
+    "ecom/delivery-profile"
+  ],
+  "blockedSourceDependencies": [
+    {
+      "sourceEntityRef": "plugin.woo-checkout-field-editor-pro.checkout-field-definition",
+      "degradedField": "extendedFields",
+      "pitfallCode": "checkout-custom-field-values-need-definitions",
+      "degradation": "deferred"
+    }
+  ],
   "sourceAliases": [
-    { "sourceSystem": "woocommerce", "sourceEntity": "order", "routes": ["/wc/v3/orders"], "confidence": "high" },
-    { "sourceSystem": "wix", "sourceEntity": "ecomOrder", "routes": ["eCommerce Orders API"], "confidence": "high" }
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "ecomOrder",
+      "routes": [
+        "eCommerce Orders API"
+      ],
+      "confidence": "high"
+    }
   ],
   "preferredWrite": {
     "surface": "eCom Orders",
     "endpoint": "POST /ecom/v1/orders/import",
     "writerId": "importOrder",
-    "verification": "unverified",
+    "verification": "verified-live",
     "importSafe": true,
     "bulk": false,
     "releaseStatus": "beta",
-    "decision": "Import Order is the dedicated migration path (ECOM-01): settable purchasedDate/createdDate/number, values stored as-is, no side effects (no buyer notifications, no inventory adjustment, no contact/invoice/receipt/subscription creation; only the OrderImported event fires). Beta, single-order only (no bulk endpoint), no SHOPIFY/WOOCOMMERCE channel enums (use OTHER_PLATFORM), analytics inclusion not suppressible. Rollback via Bulk Delete Imported Orders; re-send with the same id fully replaces."
+    "decision": "Import Order is the dedicated migration path: settable purchasedDate/number (createdDate is NOT settable -- see pitfalls), values stored as-is, no side effects (no buyer notifications, no inventory adjustment, no contact/invoice/receipt/subscription creation; only the OrderImported event fires). Beta, single-order only (no bulk endpoint), no SHOPIFY/WOOCOMMERCE channel enums (use OTHER_PLATFORM), analytics inclusion not suppressible. Rollback via Bulk Delete Imported Orders (VERIFIED LIVE 2026-09-05: async jobId, orders gone within seconds, a deleted id can be re-imported). Caller-supplied `id` VERIFIED LIVE 2026-09-05 (disposable site): a never-seen GUID is ACCEPTED and kept, so the order write can be made idempotent by deriving the id from the source -- `lib/order-history.js` does this; a re-send with an existing id fully REPLACES the body (omitted fields are cleared, createdDate kept, updatedDate moves, the number can change) while attached payments and extendedFields SURVIVE; a non-GUID id is a 400. See the silent-replace pitfall."
   },
   "alternateWrites": [
     {
@@ -32,9 +65,63 @@
       "verification": "unverified",
       "importSafe": false,
       "bulk": false,
-      "when": "Live-commerce order creation only — NEVER for historical import: decrements inventory, sends buyer confirmation email, auto-creates a contact (ECOM-02)."
+      "when": "Live-commerce order creation only \u2014 NEVER for historical import: decrements inventory, sends buyer confirmation email, auto-creates a contact."
     }
   ],
+  "extendedFields": {
+    "schemaKind": "data-extension-schema",
+    "definitionSurface": "Data Extension Schema API",
+    "definitionOperation": "Create/Update Data Extension Schema (FQDN wix.ecom.*.order)",
+    "valuePath": "extendedFields.namespaces._user_fields",
+    "namespaceForCreatedFields": "_user_fields",
+    "dataExtensionSchemaBacked": true,
+    "keyConvention": "wpCheckout_<metaKey> for values sourced from a checkout-field-editor-style plugin \u2014 avoids collision with merchant-created or other-plugin _user_fields entries.",
+    "fieldTypeMapping": [
+      {
+        "csvType": "text",
+        "fieldType": "string",
+        "notes": "maxLength 255 default"
+      },
+      {
+        "csvType": "textarea",
+        "fieldType": "string",
+        "notes": "maxLength 2000 default"
+      },
+      {
+        "csvType": "select",
+        "fieldType": "string",
+        "notes": "options documented in description, not enforced \u2014 DES has no enum"
+      },
+      {
+        "csvType": "radio",
+        "fieldType": "string",
+        "notes": "same as select"
+      },
+      {
+        "csvType": "multiselect",
+        "fieldType": "array",
+        "notes": "items: string"
+      },
+      {
+        "csvType": "checkbox",
+        "fieldType": "boolean",
+        "notes": "single yes/no field"
+      },
+      {
+        "csvType": "date",
+        "fieldType": "string",
+        "notes": "format: date"
+      }
+    ],
+    "docs": [
+      "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/import-order",
+      "https://dev.wix.com/docs/api-reference/business-management/data-extension-schema/introduction"
+    ],
+    "fqdn": "wix.ecom.*.order",
+    "supportsFiltering": false,
+    "nestedSubrecordExtendedFields": "unknown \u2014 which order subrecords expose nested extendedFields is open and out of scope; never provision nested fields",
+    "liveVerification": "Schema create/update/re-read and value writes verified live 2026-09-04 (string fields only)."
+  },
   "safeModeContactFields": [
     {
       "kind": "email",
@@ -74,24 +161,302 @@
     }
   ],
   "fallbacks": [
-    { "classification": "cms", "when": "Use for separate audit/history records or unsupported nested source details." }
+    {
+      "classification": "cms",
+      "when": "Use for separate audit/history records or unsupported nested source details."
+    }
   ],
-  "reliability": { "status": "partially-reliable", "flags": [] },
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
   "pitfalls": [
-    { "code": "create-order-not-import-safe", "severity": "blocker", "summary": "Never route historical orders through createOrder — it decrements inventory, emails the buyer, and auto-creates contacts; importOrder is the only import-safe writer." },
-    { "code": "contact-crosswalk-sequencing", "severity": "blocker", "summary": "Import creates no contact; contacts (including guest buyers from order billing emails) must be imported first so buyerInfo.contactId can be passed." },
-    { "code": "beta-single-order", "severity": "warning", "summary": "Import Order is Beta and single-order only (no bulk endpoint); undocumented rate limits apply at scale." },
-    { "code": "analytics-not-suppressible", "severity": "warning", "summary": "Imported orders appear in sales analytics/reports with no documented exclusion flag." },
-    { "code": "imported-orders-invisible-to-events", "severity": "warning", "summary": "Only the OrderImported event fires and only eCom's own indexer consumes it — imported orders never materialize in contacts/loyalty/event-driven views." }
+    {
+      "code": "create-order-not-import-safe",
+      "severity": "blocker",
+      "summary": "Never route historical orders through createOrder \u2014 it decrements inventory, emails the buyer, and auto-creates contacts; importOrder is the only import-safe writer."
+    },
+    {
+      "code": "order-number-must-be-numeric",
+      "severity": "blocker",
+      "summary": "VERIFIED LIVE 2026-08-16: `order.number` must be a numeric string. A non-numeric value (e.g. the 'WT-1042' shape produced by WooCommerce sequential-order-number plugins) fails the entire Import Order call with a bare 400 {\"message\":\"Not a numeric value\"} carrying no field path \u2014 the error does not say which field, so it reads as a malformed payload. Strip prefixes to the numeric core and ledger the original as a fidelity note; do not pass the source order number through unvalidated."
+    },
+    {
+      "code": "merchant-note-author-is-token-holder",
+      "severity": "warning",
+      "summary": "VERIFIED LIVE 2026-08-16: Add Activities stamps `authorEmail` with the login email of whoever holds the token, not the source note's author, and the timestamp is call time (not backdatable). In a partner-run migration this writes the partner's address across the merchant's whole order history \u2014 prefix the source author/date into the message body when that provenance matters. See ecom/order-merchant-note."
+    },
+    {
+      "code": "contact-crosswalk-sequencing",
+      "severity": "blocker",
+      "summary": "Import creates no contact; contacts (including guest buyers from order billing emails) must be imported first so buyerInfo.contactId can be passed."
+    },
+    {
+      "code": "beta-single-order",
+      "severity": "warning",
+      "summary": "Import Order is Beta and single-order only (no bulk endpoint); undocumented rate limits apply at scale."
+    },
+    {
+      "code": "analytics-not-suppressible",
+      "severity": "warning",
+      "summary": "Imported orders appear in sales analytics/reports with no documented exclusion flag."
+    },
+    {
+      "code": "imported-orders-invisible-to-events",
+      "severity": "warning",
+      "summary": "Only the OrderImported event fires and only eCom's own indexer consumes it \u2014 imported orders never materialize in contacts/loyalty/event-driven views."
+    },
+    {
+      "code": "checkout-custom-field-values-need-definitions",
+      "severity": "warning",
+      "summary": "A checkout-field-editor-style plugin's custom field VALUES ride as unregistered order postmeta with no fixed key or envelope (see woo-checkout-field-editor-pro.json's values-have-no-fallback-envelope-key pitfall) \u2014 they cannot be identified, let alone written as extendedFields.namespaces._user_fields entries, until the field list (label/type/meta-key) is known. Without it, these values are not degraded, they are entirely unattempted."
+    },
+    "buyerInfo.memberId is what member-facing reads authorize on. A member-identity Get Order returns an order only if that member placed it, and the invoice download backend checks the same field again itself -- so an imported order carrying only buyerInfo.contactId is invisible to its own buyer, and one attributed to the WRONG member hands that member someone else's invoice. Both checks read the same stored value, so neither catches a bad crosswalk. Setting and validating buyerInfo.memberId is a prerequisite of any member-facing order feature, not something those features can verify.",
+    "VERIFIED LIVE 2026-09-05: `createdDate` sent to Import Order is IGNORED. The order reads back with createdDate = the moment of the import, while `purchasedDate` and the payment record's own createdDate both hold the real source dates. Earlier notes here claimed createdDate was settable; the live sentinel printed it but only ever asserted purchasedDate, so the claim was never actually tested. Do not report createdDate as preserved history, and do not use it to reconcile against a source date -- purchasedDate is the field that carries when the order happened.",
+    "LIVE-FOUND 2026-09-05: Import Order rejects an order with no `status` and no `billingInfo.contactDetails` -- 400 \"status value is required\" and \"contactDetails must not be empty\". A billing ADDRESS alone does not satisfy it. Neither field is obvious from the response shape, and the 400 names them only once you have already omitted them.",
+    {
+      "code": "existing-id-replaces-silently",
+      "severity": "blocker",
+      "summary": "VERIFIED LIVE 2026-09-05: Import Order with the `id` of an EXISTING imported order replaces its whole body with no conflict response -- nothing distinguishes \"replace my own earlier import\" from \"overwrite the merchant's edits since\", and an omitted field is cleared rather than kept. So never re-send an order that already exists: `lib/order-history.js` reads by derived id on a crosswalk miss and reconciles an existing order instead of importing. Payments and extendedFields do survive a replace, so an accidental one loses order-body edits, not payment history or preserved documents."
+    },
+    {
+      "code": "buyerinfo-memberid-stored-unvalidated",
+      "severity": "blocker",
+      "summary": "VERIFIED LIVE 2026-09-05 (fresh site): Import Order accepts `buyerInfo.memberId` with or without `contactId` and reads it back; it ALSO accepts a memberId that is not a member on the site and stores it as-is -- no validation, no error. Since member-facing reads and the invoice download authorize on this field, a wrong value hands one member another's order. The field is set only from `lib/order-buyer.js` resolveOrderBuyer -- member crosswalk row whose loginEmail equals the order's billing email -- stamped; the composite refuses a caller-set memberId on the body and requires the body's buyerInfo.email to be the email the member was corroborated against. That corroborated-email requirement applies to the SOURCE-DERIVED body, checked once before the first send; a contact-field retry may send the verified memberId without the email Import Order's rejection named, keeping memberId and contactId unchanged. A memberId alone reads back without a contactId (no derivation)."
+    },
+    {
+      "code": "malformed-contact-value-fails-the-whole-order",
+      "severity": "blocker",
+      "summary": "OBSERVED LIVE: a single email or phone Import Order refuses -- on billingInfo, shippingInfo or buyerInfo -- fails the ENTIRE order, not just that field. The source's validation is weaker than Wix's, so real historical orders carry values the source stored happily (see crm/contact's source-email-can-fail-the-target-validator for the observed email shape), and they surface on live orders rather than in testing. The rule is order-contact-field-refused-fails-whole-order above; this entry does not widen it. Remove only the email or phone field the rejection itself names and send the order once more; if that single retry is also refused, the order is `order-import-failed` -- reported as failed, its source record and rejection kept, and listed for a person to act on. Never remove, rewrite or invent a value on a local check alone (a local check only warns), and never add a second retry or a runner-side drop around the composite. Three consequences to plan and report for: (1) the removed value is not on the imported order and must not be assumed to exist on the linked contact -- it stays recoverable only from the run's on-disk source extraction, and no result, journal row, report or repo file carries the value itself; (2) an order imported without a field is a fidelity loss, not a clean import: it reads back complete, so only its order-contact-email-dropped / order-contact-phone-dropped finding separates it from a fully preserved order, and a reconciliation that compares counts or re-reads orders cannot see it; (3) Import Order still requires `billingInfo.contactDetails` to be non-empty, so removing the named field can leave the order invalid -- the retry is then refused and the order fails; do not remove further fields to get it through."
+    },
+    {
+      "code": "member-area-order-history-list-matches-by-contactid-not-memberid",
+      "severity": "info",
+      "summary": "LIVE-VERIFIED 2026-09-16: a customer promoted from a safe-mode contact to a real-email Member AFTER their orders were already imported with only `buyerInfo.contactId` (no `memberId` -- the promotion flow never resends Import Order) could immediately see their full order history in the site's Member Area, with no order-backfill write at all. This does NOT contradict `buyerinfo-memberid-stored-unvalidated` above: the Member Area's order-history list is reading by the order's `buyerInfo.contactId` matching the member's OWN contactId, which is guaranteed here because promotion reuses the pre-existing contact rather than creating a new one (see crm/contact's mappingGuidance and the ensureMember composite). This is a narrower claim than 'memberId is unnecessary' -- it confirms the customer-facing order-LIST view specifically, for exactly this contactId-preserving promotion order (contacts/orders imported first, member created afterward on the same contact). It does NOT retest member-scoped API reads (a member-identity Get Order call) or invoice-download authorization, which the still-standing blocker above says authorize on `memberId` specifically and were not re-verified against a contactId-only order in this pass. Do not generalize this to 'memberId can be skipped' for any workflow that authorizes programmatically rather than through the Member Area UI."
+    },
+    {
+      "code": "order-contact-field-refused-fails-whole-order",
+      "severity": "blocker",
+      "summary": "A source email or phone Import Order refuses fails the ENTIRE order, not just the field, so the financial record is lost to a descriptive detail. Resolution: remove only a contact field the rejection itself NAMES -- a 400 whose `details.validationError.fieldViolations[].field`, after an optional leading `order.`, exactly equals a `safeModeContactFields[]` path, with no other violation -- and send the order once more under the same derived id; a second refusal is `order-import-failed`. Never remove or rewrite a field on a local or customer-path check alone (the E.164 rule in members/member `phone-must-be-e164-and-dedupes-across-contacts` is verified for Contacts/Members, not Import Order), and never invent a stand-in value. On a member-linked order the retry keeps `buyerInfo.memberId`/`contactId`. `order-history.js` `importOrderHistory` does this and emits `order-contact-email-dropped`/`order-contact-phone-dropped` (field and reason, never the value); `checkOrderContactFields` only warns (`-suspect`). NOT VERIFIED LIVE for Import Order: no contact-field rejection body has been captured. The first live rejection must record its error shape (without the value)."
+    },
+    {
+      "code": "import-order-currency-default-not-applied",
+      "severity": "blocker",
+      "summary": "Verified on a disposable site: omitting currency from Import Order stored an empty currency despite the documented site default. The dashboard order page then failed with an invalid-currency rendering error. Always provide explicit source currency; the corrected reference canary separately verified shipping/tax fidelity."
+    }
   ],
   "mappingGuidance": [
     "Resolve product, variation, contact, and coupon crosswalks before writing orders.",
-    "Contacts import first, orders second: Import Order accepts buyerInfo.contactId (schema-checked 2026-08-04) but creates no contact itself — always pass the crosswalked contact ID, including for guest buyers derived from order billing emails (see crm/contact). The field doc's 'automatically created if one doesn't exist' text is shared with live Create Order and is unverified for the import path — do not rely on it.",
-    "Use order and line-item extended fields for source-only metadata when configured."
+    "Contacts import first, orders second: Import Order accepts buyerInfo.contactId (schema-checked 2026-08-04) but creates no contact itself \u2014 always pass the crosswalked contact ID, including for guest buyers derived from order billing emails (see crm/contact). The field doc's 'automatically created if one doesn't exist' text is shared with live Create Order and is unverified for the import path \u2014 do not rely on it.",
+    "Use order and line-item extended fields for source-only metadata when configured.",
+    "A per-order merchant note or comment from the source (e.g. a WooCommerce order note, or a payment-gateway plugin's note field) has no import-time field \u2014 `activities[]` is read-only on Create/Import Order (dev.wix.com verified 2026-08-11). Add it as a SEPARATE follow-up call after the order is imported: POST /ecom/v1/orders/{orderId}/activities/add with activityType MERCHANT_COMMENT and merchantComment.message (max 5000 chars). This stamps authorEmail and createdDate at migration time \u2014 the original note's author and timestamp cannot be preserved; prefix the message with the original date/author if that provenance matters.",
+    "Source order notes map to merchant comment activities (POST /ecom/v1/orders/{id}/activities) after the order import, preserving original author/date inside the message text \u2014 verified live 2026-08-12.",
+    "Always set channelInfo = { type: \"OTHER_PLATFORM\", externalOrderId: <source order id>, externalOrderUrl: <source order edit link, if constructible> }. This documented field makes the source identity visible on the Wix order as well as in the local crosswalk. lib/order-channel-build.js's buildChannelInfo() constructs it; the caller constructs or omits externalOrderUrl because legacy post-based order storage and WooCommerce HPOS use different admin URL shapes.",
+    "If the order bought a gift card, import that line item normally and use the gift-card crosswalk for later redemption linking. If the order redeemed a gift card as payment, do not reconstruct that from WooCommerce order data because the required source signal is absent from /wc/v3/orders. Record an explicit blocked capability until verified source gift-card activity data is available; lib/gift-card-redemption-build.js's buildGiftCardRedemption() builds the redemption call from that activity row.",
+    "ADDED 2026-08-17 \u2014 full sub-object review against the live Import Order request schema (dev.wix.com, fetched 2026-08-17), reconciled with the already-live-verified sibling entities (order-line-item, order-line-item-options, order-applied-discount, order-merchant-note, order-refund):",
+    "lineItems[].catalogReference is optional overall (a custom, non-catalog line has none) but catalogItemId+appId are required together when it is present, as verified by gift-card orders imported without catalogReference. appId picks the dependency: Wix Stores' fixed app id -> stores/product; the Wix Gift Cards app id (d80111c5-a0f4-47a8-b63a-65b54d774a27, see domains/gift-cards/domain.json) -> gift-cards/gift-card-product. Resolve the crosswalk for whichever catalog the line actually belongs to \u2014 never assume Stores.",
+    "Verified on a disposable site with explicit source currency: omit shippingInfo.carrierId and shippingInfo.code for historical order import while preserving the single source shipping line title, price and available logistics. Both isolated and combined omission preserved the shipping method and cost in Get Order and the dashboard. Included target references must still resolve through current, fully passed setup evidence; never use source or invented IDs.",
+    "Verified on a disposable site: omit lineItems[].taxInfo.taxGroupId while preserving explicit source tax amounts and the order-level breakdown. Isolated and combined omission preserved tax display. The order-level taxInfo.taxBreakdown entries have tax name/type/rate/aggregated amount, not a taxGroupId field. Required setup edges remain task-complete.",
+    "Reviewed and found to need NO crosswalk dependency (plain data, no other-entity reference): recipientInfo (final-recipient address/contact, distinct from shippingInfo.logistics.shippingDestination \u2014 both are just address+contact data), businessLocation.id (a Wix Locations id; no domain entity models Locations in this repo yet \u2014 treat as informational/omit if the source has no location concept), customFields/extendedFields (free-form key:value, extendedFields additionally requires the namespace to be pre-configured in the app dashboard \u2014 a setup step, not an entity crosswalk), lineItems[].subscriptionInfo (subscription cycle metadata carried as-is, no subscription-entity crosswalk found on the Import Order path), additionalFees (free-form fee records, no crosswalk), buyerNote/tags/weightUnit/currency/taxIncludedInPrices/attributionSource/buyerLanguage (scalar/enum fields, no dependency).",
+    "purchasedDate/number are settable on import and immutable after (order.number must additionally be numeric \u2014 see the order-number-must-be-numeric pitfall); createdDate/updatedDate/fulfillmentStatus/createdBy/currencyConversionDetails (once set) are read-only or import-then-immutable \u2014 do not attempt to set the ones docs mark read-only, and do not rely on an LLM-summarized docs read for this distinction without cross-checking wix-writers.js's own live-verified required-field comment on buildImportOrderRequest, which already caught fields a generic docs summary got wrong (e.g. incorrectly claiming catalogReference is unconditionally required).",
+    "Never resend an existing derived order ID to backfill shipping. Preserve existing-order adoption. Use the verified bundled omission mapping for the tested scope; a changed or unverified mapping remains blocked until a disposable-site canary proves source title/cost/tax and dashboard fidelity; API acceptance alone proves no meaning. Zero source shipping lines omit shippingInfo; one maps source title/cost; multiple defer with order-multiple-shipping-lines and a blocker gap. Setup-produced edges always require every bound step to pass. Use only gate-owned setup-reference resolutions for any required target IDs."
+  ],
+  "setupRequirements": [
+    "Order data extension schema if extended fields are used.",
+    "Side-effect verification before execution."
   ],
-  "setupRequirements": ["Order data extension schema if extended fields are used.", "Side-effect verification before execution."],
   "evidence": [
-    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.md" },
-    { "type": "repo-research", "path": "research/source-entity-import-suitability-wordpress-woocommerce-wix.md" }
-  ]
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-object",
+      "note": "object page (docs-survey sweep 2026-08-11)"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/add-activities",
+      "note": "Add Activities with activityType MERCHANT_COMMENT is the verified post-import path for a source order note or comment."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: create + query-back readback, safe mode on \u2014 orders via the import-safe Import Order flow, read back; no notification/inventory side effects observed"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/import-order",
+      "note": "A full Import Order request-schema review cross-checked every field against live-verified sibling entities and wix-writers.js. Live gift-card order imports without catalogReference confirmed that the field is optional overall."
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification",
+      "note": "Order <anonymized-id> imported via POST /ecom/v1/orders/import with lineItems carrying only quantity/itemType/productName/price \u2014 no catalogReference \u2014 and succeeded, confirming catalogReference is genuinely optional on this endpoint."
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification",
+      "note": "Import Order id semantics, confirmed by probes on a disposable site: never-seen v4 and derived v5-style GUIDs accepted and returned unchanged; same-id re-send is a full replace (createdDate kept, updatedDate moved, omitted purchasedDate cleared, one order per number); payments and extendedFields survive the replace; extendedFields settable through Import Order; non-GUID id -> 400; Bulk Delete Imported Orders returns a jobId and a deleted id re-imports. One refuted: Search Orders by the OLD number still matched ~1s after a renumber (eventually consistent) -- search is not an existence check."
+    },
+    {
+      "type": "live-verification",
+      "path": "anonymized-live-verification",
+      "note": "Nine synthetic historical Import Order cases with explicit currency were each accepted, read back and inspected in the dashboard, after requiring the all-valid baseline to pass first. Shipping and line-item tax references were independently omitted, jointly omitted, individually invalidated, or partially omitted. Source shipping title/cost and explicit tax amounts/breakdown displayed faithfully in all nine. The selected combined omission is the tested joint-omission case. Invalid IDs were stored verbatim and confer no permission to invent references; setup dependencies remain task-complete."
+    }
+  ],
+  "intendedFields": [
+    {
+      "targetPath": "order.number",
+      "sourcePaths": [
+        "number"
+      ]
+    },
+    {
+      "targetPath": "order.lineItems[]",
+      "sourcePaths": [
+        "lineItems[]"
+      ]
+    },
+    {
+      "targetPath": "order.billingInfo",
+      "sourcePaths": [
+        "billingInfo"
+      ]
+    },
+    {
+      "targetPath": "order.shippingInfo",
+      "sourcePaths": [
+        "shippingInfo"
+      ]
+    }
+  ],
+  "readBackProjection": {
+    "identity": "derived-id-and-sent-number",
+    "serverOwned": [
+      {
+        "path": "order.createdDate",
+        "reason": "import ignores creation timestamp"
+      },
+      {
+        "path": "order.updatedDate",
+        "reason": "server timestamp"
+      },
+      {
+        "path": "order.activities",
+        "reason": "server history"
+      }
+    ],
+    "read": "GET /ecom/v1/orders/{id}",
+    "arrays": {
+      "lineItems": "id",
+      "appliedDiscounts": "content"
+    }
+  },
+  "dependencyModes": {
+    "crm/contact": "per-record",
+    "stores/product": "per-record",
+    "stores/coupon": "per-record",
+    "gift-cards/gift-card": "per-record"
+  },
+  "dependencyReferenceFields": {
+    "crm/contact": [
+      "buyerInfo.contactId"
+    ],
+    "stores/product": [
+      "lineItems[].catalogReference.catalogItemId"
+    ],
+    "stores/coupon": [
+      "appliedDiscounts[].coupon.id"
+    ],
+    "gift-cards/gift-card": [
+      "appliedDiscounts[].giftCard.id"
+    ],
+    "ecom/shipping-option": [
+      "shippingInfo.code"
+    ],
+    "ecom/delivery-profile": [
+      "shippingInfo.carrierId"
+    ],
+    "tax/tax-group": [
+      "lineItems[].taxInfo.taxGroupId"
+    ]
+  },
+  "importReferenceCanary": {
+    "verifiedAt": "2026-10-19",
+    "scope": "historical Import Order with a synthetic custom item, explicit currency, one shipping line and preserved explicit tax breakdown",
+    "taxGroupPath": "lineItems[].taxInfo.taxGroupId",
+    "selectedCell": 4,
+    "cells": [
+      {
+        "cell": 1,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 2,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 3,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 4,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 5,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 6,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 7,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 8,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      },
+      {
+        "cell": 9,
+        "accepted": true,
+        "readBackVerified": true,
+        "dashboardVerified": true,
+        "shippingFidelity": true,
+        "taxFidelity": true
+      }
+    ]
+  }
 }

package/skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/pickup-location.json

@@ -0,0 +1,122 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "pickup-location",
+  "displayName": "Wix Pickup Location",
+  "capability": "commerce.pickup-location",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "PickupLocation",
+    "verifiedFqdn": "wix.ecom.v1.pickup_location",
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "ecom/delivery-profile"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "shipping-zone.method[local_pickup|pickup_location]",
+      "routes": [
+        "/wc/v3/shipping/zones/{id}/methods"
+      ],
+      "confidence": "high",
+      "note": "shipping-build.js's classifyMethod returns kind:'pickup' for these two method_ids. That classification produces a PickupLocation and NEVER a ShippingOption. It does NOT mean no carrier: the Pickup DeliveryCarrier must still be attached, with backupRate {amount '0', active FALSE}, or the collection point does not render at checkout at all -- see the attach-the-pickup-carrier blocker pitfall. What the classification is terminal about is the SHIPPING side: no ShippingOption, and no delivery carrier of any other role."
+    },
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "settings.pickup_locations",
+      "routes": [
+        "/wp/v2/settings"
+      ],
+      "confidence": "high",
+      "note": "WooCommerce Blocks Local Pickup stores its locations as WordPress options surfaced on the core settings route -- NOT under /wc/v3/. This route is already part of the default discovery sweep, so a Blocks source's pickup addresses are already captured; they just had no consumer until now."
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Pickup Locations",
+    "endpoint": "POST https://manage.wix.com/_api/pickup-locations/v1/pickup-locations (the public www.wixapis.com host 404s — see the host pitfall)",
+    "writerId": "createPickupLocation",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": true,
+    "releaseStatus": "beta",
+    "decision": "Collection points are their own entity on their own service host. Bulk create/update/delete exist (max 100 per call) but a migration rarely has more than a handful of collection points, so the single create is the default path."
+  },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "pickup-is-not-a-shipping-option",
+      "severity": "blocker",
+      "summary": "A source local_pickup method must NEVER be written as a ShippingOption. A ShippingOption has no app/carrier/role field, so a 0-amount collection option renders at checkout as a free DELIVERY sitting next to the real paid delivery -- buyers pick it expecting their order shipped for nothing. Observed live: collection rendered as a 0-priced shipping choice beside a paid one. The classification is terminal: kind:'pickup' produces a PickupLocation and no shipping option."
+    },
+    {
+      "code": "attach-the-pickup-carrier-but-never-with-an-active-backup-rate",
+      "severity": "blocker",
+      "summary": "Two facts that look contradictory and are not. (a) A Pickup carrier whose backupRate is ACTIVE renders as a 0-priced DELIVERY row beside the paid one -- live-observed, alongside a duplicate 0-priced shipping option for the same collection point. (b) But removing the Pickup carrier ENTIRELY made the collection point stop appearing at all, even though the PickupLocation still existed, was active, and was bound to the region -- observed live after exactly that removal. The correct shape is therefore: attach the Pickup carrier so the region can render collection, with backupRate {amount '0', active FALSE} so the carrier itself never becomes a delivery row -- and create the PickupLocation for the actual collection point. Never an active backupRate, never no carrier at all. resolvePickupAppId is how the Pickup app's installation-scoped appId is resolved; it IS a write path after all, just a carefully constrained one."
+    },
+    {
+      "code": "address-is-required-and-only-one-source-shape-has-one",
+      "severity": "blocker",
+      "summary": "`address` (with at least `country`) is required by the create call, and whether the source has one depends entirely on WHICH pickup implementation it uses. BLOCKS Local Pickup (`pickup_location` method) keeps real locations WITH addresses in WordPress options, exposed on GET /wp/v2/settings as `pickup_locations[]` = {name, address:{address_1, city, state, postcode, country}, details, enabled} plus `pickup_location_settings` = {enabled, title, tax_status, cost}. LEGACY `local_pickup` (a shipping-zone method) carries only {title, tax_status, cost} -- no address, no linked record, nothing to read; its town is often named inside the method's own TITLE text, which is a label and must never be parsed as an address. So check the Blocks locations FIRST (shipping-build.js's resolvePickupAddressSource): a Blocks source needs no human input at all, while a legacy source can only be answered by the merchant. buildPickupLocationInput throws without an address either way, because the server-side failure carries far less context than the local one."
+    },
+    {
+      "code": "blocks-global-settings-gate-the-locations-and-carry-the-fee",
+      "severity": "blocker",
+      "summary": "BLOCKS Local Pickup splits its configuration in two, and the GLOBAL half owns things no individual location carries: `pickup_location_settings` = {enabled, title, tax_status, cost}. (1) `enabled` is the MASTER SWITCH. Every location can be individually `enabled: true` while pickup as a whole is off, so reading only the per-location flag re-enables a fulfillment method the merchant deliberately turned off, and Wix checkout starts offering collection. Both gates must pass: a location is active only when the global switch is not explicitly off AND the location itself is not `enabled: false`. WooCommerce writes this as the strings yes/no on some routes and as a real boolean on others, and ABSENT means \"not configured\", which for a feature switch reads as ON -- only an explicit no/false/0/off turns it off. (2) `cost` is the collection FEE, set ONCE for all locations. Blocks pickup has no per-zone cost field, so the zone method's own `settings.cost` -- which is where the LEGACY local_pickup method correctly keeps its fee -- is absent for this shape and the classification reads 0. Read the fee from the global settings and pass it to buildPickupLocationInput's `amount`, or every pickup order silently charges nothing. shipping-build.js's pickupLocationsFromWpSettings returns both the resolved `active` and the `amount` per location, so a caller never has to know which half of the config they came from."
+    },
+    {
+      "code": "shipping-rule-id-is-deprecated-and-internal",
+      "severity": "warning",
+      "summary": "`shippingRuleId` is deprecated, marked internal, and replaced by `deliveryRegionIds`, with a removal target already in the past. Wix's own dashboard front-end still sends it; that is not a reason for a migration to. Send `deliveryRegionIds` only."
+    },
+    {
+      "code": "delivery-regions-are-not-updatable-through-update",
+      "severity": "warning",
+      "summary": "The Update call cannot change region membership -- the service says so explicitly. Use the dedicated Add Delivery Region / Remove Delivery Region calls on the pickup location (each takes pickupLocationId + deliveryRegionId + revision). Note the name collision with the Delivery Profiles API's own addDeliveryRegion, which adds a REGION TO A PROFILE; this one adds a PICKUP LOCATION TO A REGION."
+    },
+    {
+      "code": "create-failed-precondition-limits",
+      "severity": "warning",
+      "summary": "Create can fail FAILED_PRECONDITION with LOCATIONS_IN_SHIPPING_RULE_LIMIT_EXCEEDED or LIMIT_OF_OPTIONS_PER_DELIVERY_REGION_EXCEEDED. Caps: deliveryRegionIds max 50 per location, rates max 50, name 1-100 chars, deliveryTime max 500, instructions max 1000."
+    },
+    {
+      "code": "documented-public-host-404s-use-the-dashboard-proxy",
+      "severity": "blocker",
+      "summary": "LIVE-VERIFIED 2026-09-01, and NOT what the service's own documentation says. Its documentation.yaml declares `host: www.wixapis.com/pickup-locations`, but EVERY path under that host returns 404 with a valid site token -- both the hyphenated and camelCase spellings, and the /ecom/ prefix too. The service is BETA and is not exposed on the public gateway yet. The route that works is the dashboard proxy, `https://manage.wix.com/_api/pickup-locations/v1/pickup-locations`, which accepts the same CLI-minted site token. wix-writers.js's resolvePickupLocationsBase probes the public host first and falls back to the proxy on 404 (rethrowing anything else, so a 401/403 is never hidden behind a fallback), so this starts using the public host by itself once Wix exposes it. Permission scopes are unchanged: ECOM.PICKUP_LOCATION_CREATE / _READ / _UPDATE / _DELETE."
+    },
+    {
+      "code": "a-blank-address-is-a-real-choice-but-cannot-mean-absent",
+      "severity": "warning",
+      "summary": "Plenty of merchants coordinate collection by phone and deliberately do not publish a street -- the source method's own title usually says exactly that. That is a legitimate configuration, NOT missing data, and must not be treated as a failure to migrate. But `address` is required by the create call, so 'blank' cannot mean omitted. The honest minimum is the one part actually known: the country, DERIVED from the delivery region the location is bound to (shipping-build.js's buildMinimalPickupAddress), with no street, city or postcode invented to fill the gap. The location's `name` is then what tells buyers where and how to collect. Two guards: a region spanning more than one country has no single answer and throws rather than picking one; and a country-plus-city collection point (no street) was CREATED AND READ BACK LIVE 2026-09-01, address {country, city} preserved exactly as sent. How it renders at checkout is still worth one look."
+    }
+  ],
+  "mappingGuidance": [
+    "Two source shapes, checked in this order. (1) BLOCKS: `pickup_locations[]` on /wp/v2/settings already holds real locations -- map name -> name, address.address_1 -> addressLine (whole line, unparsed), address.city -> city, address.state -> subdivision, address.postcode -> postalCode, address.country -> country, details -> instructions, enabled -> active. Note `state` is a SEPARATE field here, unlike the store address's COUNTRY:STATE packing. (2) LEGACY `local_pickup` zone method: one PickupLocation per method, bound to the delivery region built from that method's zone via deliveryRegionIds[]; the method's title becomes `name` and its cost the single rate (a non-numeric cost falls back to 0 and is flagged).",
+    "`address` cannot be derived from a LEGACY method -- resolve it from the store address as a proposal the merchant confirms, or ask. `deliveryTime` has no WooCommerce counterpart in either shape; leave it unset rather than inventing a value. `instructions` maps from a Blocks location's `details`, and has no legacy counterpart.",
+    "Never also create a ShippingOption for the same method -- that re-creates the 0-priced-delivery defect this entity exists to avoid. The Pickup DeliveryCarrier is the opposite case and must NOT be omitted: attach it with backupRate {amount '0', active FALSE}. An ACTIVE backup rate re-creates the same 0-priced-delivery row, and no carrier at all makes the collection point vanish from checkout even though the PickupLocation exists and is bound to the region -- both were observed live. See the two blocker pitfalls above.",
+    "A zone whose only enabled method is pickup is NOT a checkout dead end -- collection is a real way to receive an order -- so it does not get delivery-profile.json's missing-rates alert even though it offers no DELIVERY rate. It still carries the Pickup carrier; that carrier's backup rate is inactive by design, so the zone has a carrier and no deliverable rate at the same time, which is the correct shape here rather than the gap the alert looks for.",
+    "A merchant who declines to publish a street address gets a country-only address derived from the delivery region, and the full source method title as `name`. Reach that branch only through an explicit decline (resolvePickupAddressSource's `addressDeclined`) -- never as a silent fallback when an address could not be found, because those two states need different follow-ups."
+  ],
+  "setupRequirements": [
+    "Wix Stores app (eCommerce checkout) — the site's default delivery profile must exist so a delivery region id is available to bind to."
+  ],
+  "objectPageException": "The public API-reference tree for shipping and delivery exposes Delivery Profiles only; there is no PickupLocations subsection and no '…-object' page for this entity anywhere in it. The field shape, limits, deprecations, error codes, host and permission names are taken from Wix's own service contract for the resource instead.",
+  "evidence": [
+    {
+      "type": "service-definition",
+      "path": "wix-internal-service-definition",
+      "note": "Wix's own PickupLocations service contract and its shipped create/query examples: entity fields and limits, the required-on-create set, the shippingRuleId deprecation and its replacement, the Add/Remove Delivery Region calls, the FAILED_PRECONDITION application codes, the public REST host, and the permission names. Read directly from the service definition rather than from a documentation page."
+    },
+    {
+      "type": "service-definition",
+      "path": "wix-internal-service-definition",
+      "note": "PickupLocation.rates is the same ConditionalRates type as ShippingOption.rates, so the conditional-rate shape documented on ecom/shipping-option applies here unchanged."
+    }
+  ],
+  "notes": "Authored to close the pickup half of the shipping phase-2 work: phase 1 wrote collection points as shipping options, which is what put a 0-priced delivery next to a paid one. Create and read-back VERIFIED LIVE 2026-09-01, through the dashboard proxy host (the documented public host 404s -- see its pitfall). A country+city address with no street round-tripped exactly. What is still unverified is purely cosmetic: how a street-less collection point renders at checkout."
+}