@wix/agent-skills 1.33.0 → 1.34.0

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

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-line-item-options",
+  "displayName": "eCommerce Order Line Item Options (Description Lines)",
+  "capability": "commerce.order-addon-values",
+  "target": {
+    "classification": "native-plus-cms",
+    "nativeEntity": "eCommerce Order Line Item Description Lines",
+    "verifiedFqdn": null,
+    "idPolicy": "not-applicable",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "media/media-file"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order_item_addon_value",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "ecomOrderLineItemDescriptionLine",
+      "routes": [
+        "eCommerce Orders API"
+      ],
+      "confidence": "high"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Orders",
+    "endpoint": "POST /ecom/v1/orders/import",
+    "writerId": "importOrder",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    {
+      "classification": "cms",
+      "when": "Use a CMS shadow (keyed by the order crosswalk + line item) for the raw addon payload when fidelity matters, or when values overflow the descriptionLines caps (20 lines / 600 chars per value)."
+    }
+  ],
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "modifier-groups-read-only-on-import",
+      "severity": "warning",
+      "summary": "lineItems[].modifierGroups is READ-ONLY on import: it is absent from the Import Order writable request body and marked read-only (maxItems 10) on the returned Order object — addon values can never be recreated as structured modifiers on historical orders. descriptionLines[] is the import-time carrier. VERIFIED LIVE 2026-08-16: an imported line item carrying descriptionLines and catalogReference.options read back with modifierGroups: [] — the field stays empty even when the referenced catalog product genuinely has modifiers attached."
+    },
+    {
+      "code": "description-lines-readback-adds-legacy-mirrors",
+      "severity": "info",
+      "summary": "VERIFIED LIVE 2026-08-16: the readback of a description line adds server-computed legacy mirror fields alongside what was sent — plainText lines gain lineType: 'PLAIN_TEXT' plus a duplicated plainTextValue, and colorInfo lines gain lineType: 'COLOR' plus a flattened color string. Verification/diff passes must compare only the fields that were sent, or they will report spurious drift."
+    },
+    {
+      "code": "catalog-reference-options-is-untyped",
+      "severity": "info",
+      "summary": "VERIFIED LIVE 2026-08-16: lineItems[].catalogReference.options accepts and preserves arbitrary key:value string pairs verbatim (probe carried variantId, a source addon group id, and a human-labelled addon value side by side). Nothing validates the keys against the referenced product's real customizations, so a typo here is silent — it is a machine-readable carry, not a checked link."
+    },
+    {
+      "code": "description-lines-caps",
+      "severity": "warning",
+      "summary": "descriptionLines caps: max 20 lines per line item; name.original max 100 chars; value is a one-of plainText (original max 600 chars) OR colorInfo (never both). Sources with >20 addon fields per line item or values >600 chars overflow to the CMS shadow or truncate with a ledger entry."
+    },
+    {
+      "code": "display-only-semantics",
+      "severity": "warning",
+      "summary": "descriptionLines are display-purpose text on the cart/checkout/order — not machine-readable selections. Mirror machine-readable selections into lineItems[].catalogReference.options (writable key:value object) when downstream logic needs them; text-only carry loses structure."
+    },
+    {
+      "code": "file-upload-values-need-media-copy",
+      "severity": "warning",
+      "summary": "Addon values that are file uploads reference files hosted on the source site. They need a media copy step (import the file to Wix Media, rewrite the reference) before the value is written; a bare source URL in a description line dies with the source site."
+    }
+  ],
+  "mappingGuidance": [
+    "captured addon/option values on historical order line items map to Import Order lineItems[].descriptionLines[] — one line per addon field, name.original = field title (max 100 chars), plainText.original = captured value (max 600 chars) — written on the order import payload (ecom/order).",
+    "plainText and colorInfo are a one-of per description line; addon values are text, so use plainText (colorInfo only for genuine color selections with a name and optional HEX/RGB code).",
+    "Optionally mirror machine-readable selections into lineItems[].catalogReference.options — a writable key:value object for item-selection specificity — in addition to the display-oriented description lines.",
+    "modifierGroups is read-only on import — never plan it as a target for addon values; record that explicitly in mapping reports.",
+    "File-upload addon values need a media copy step first (Wix Media import + reference rewrite); keep the original source URL in the migration ledger.",
+    "When full fidelity matters (raw source payload such as PPOM's _ppom_fields hidden meta), shadow the untruncated payload to a CMS collection keyed by the order crosswalk + source line item id.",
+    "Written through the parent order payload — never a standalone write; sequencing and crosswalks are the parent order's (ecom/order).",
+    "dependsOn media/media-file is conditional, not universal: only orders whose addon values include file uploads need the media copy step before write. Plain text/color addon values have no dependency at all."
+  ],
+  "setupRequirements": [
+    "Media copy step for file-upload addon values before order import.",
+    "CMS shadow collection setup only if the raw-payload fallback is used.",
+    "Side-effect verification before historical order execution (inherited from ecom/order)."
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/import-order",
+      "note": "Import Order request schema, markdown fetched 2026-08-16: lineItems[].descriptionLines[] writable (minItems 0, maxItems 20; one-of plainText.original maxLength 600 / colorInfo.original maxLength 500 + code; name.original maxLength 100); lineItems[].catalogReference.options writable object ('Additional item details in key:value pairs'); modifierGroups is ABSENT from the writable request body and appears read-only (maxItems 10) on the returned Order object."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-object",
+      "note": "Order object page (read 2026-08-16): descriptionLines, catalogReference, and modifierGroups confirmed on the order line item object."
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/capabilities-pending-decision.json",
+      "note": "commerce.order-addon-values pending-register entry (researched 2026-08-16 against PPOM plugin source v34.0.8; source payload shape source-verified, not live-verified — no PPOM order existed on the test site); resolved by this entity 2026-08-16."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: Import Order create and GET readback preserved plainText and colorInfo descriptionLines plus catalogReference.options exactly as sent. A line item without descriptions read back with descriptionLines: [], and modifierGroups read back empty. Probe records were deleted after verification."
+    }
+  ],
+  "notes": "Authored 2026-08-16. Promoted to verified-live 2026-08-16 by a create/readback/delete probe on an anonymized verification environment: descriptionLines (plainText and colorInfo variants) and catalogReference.options both persisted verbatim, and modifierGroups was confirmed empty on readback."
+}

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

@@ -3,6 +3,7 @@
   "domain": "ecom",
   "entity": "order-line-item",
   "displayName": "eCommerce Order Line Item",
+  "capability": "commerce.order-line-items",
   "target": {
     "classification": "native-plus-cms",
     "nativeEntity": "eCommerce Order Line Item",
@@ -10,28 +11,75 @@
     "idPolicy": "server-assigned",
     "crosswalkRequired": true
   },
+  "dependsOn": [
+    "stores/product"
+  ],
   "sourceAliases": [
-    { "sourceSystem": "woocommerce", "sourceEntity": "order_line_item", "routes": ["/wc/v3/orders"], "confidence": "high" },
-    { "sourceSystem": "wix", "sourceEntity": "ecomOrderLineItem", "routes": ["eCommerce Orders API"], "confidence": "high" }
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order_line_item",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "ecomOrderLineItem",
+      "routes": [
+        "eCommerce Orders API"
+      ],
+      "confidence": "high"
+    }
   ],
   "preferredWrite": {
     "surface": "eCom Orders",
-    "endpoint": "POST /ecom/v1/orders",
-    "writerId": "createOrder",
-    "verification": "unverified",
-    "importSafe": false,
+    "endpoint": "POST /ecom/v1/orders/import",
+    "writerId": "importOrder",
+    "verification": "verified-live",
+    "importSafe": true,
     "bulk": false
   },
   "fallbacks": [
-    { "classification": "cms", "when": "Use when source line-item metadata cannot fit native order line fields or extended fields." }
+    {
+      "classification": "cms",
+      "when": "Use when source line-item metadata cannot fit native order line fields or extended fields."
+    }
   ],
-  "reliability": { "status": "unknown", "flags": ["IMPORT_UNRELIABLE"] },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
   "pitfalls": [
-    { "code": "parent-order-write", "severity": "blocker", "summary": "Line items are written through their parent order; do not create standalone duplicates." }
+    {
+      "code": "parent-order-write",
+      "severity": "blocker",
+      "summary": "Line items are written through their parent order; do not create standalone duplicates."
+    },
+    {
+      "code": "catalog-reference-is-optional-but-paired",
+      "severity": "warning",
+      "summary": "CORRECTED 2026-08-17: catalogReference is NOT required on every line item (a custom, non-catalog line has none) — but per wix-writers.js's live-verified buildImportOrderRequest contract, when it IS present both catalogItemId and appId are required together, or the call fails. catalogItemId must be the crosswalked Wix product id (or gift-card-product id, or another catalog app's item id), never the source id — resolve stores/product's crosswalk before writing."
+    },
+    {
+      "code": "preferredWrite-was-stale",
+      "severity": "info",
+      "summary": "This entity previously pointed at createOrder (live-commerce, importSafe:false) — wrong for historical import, and inconsistent with every sibling order sub-entity (order-applied-discount, order-line-item-options) which correctly use importOrder. Corrected 2026-08-17 while doing the order-family dependency correction; line items are written through Import Order exactly like the rest of the order payload."
+    }
+  ],
+  "mappingGuidance": [
+    "Preserve source line-item IDs in extended fields or CMS shadow data.",
+    "Written through the parent order payload (ecom/order) — never a standalone write; sequencing and crosswalks (contacts, products) are the parent order's."
+  ],
+  "setupRequirements": [
+    "Order data extension schema if line-item extended fields are used."
   ],
-  "mappingGuidance": ["Preserve source line-item IDs in extended fields or CMS shadow data."],
-  "setupRequirements": ["Order data extension schema if line-item extended fields are used."],
   "evidence": [
-    { "type": "repo-research", "path": "research/import-api-suitability/orders-contacts-members.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)"
+    }
+    
   ]
 }

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

@@ -0,0 +1,112 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-merchant-note",
+  "displayName": "eCommerce Order Merchant Note (Activity)",
+  "capability": "commerce.payment-gateway-notes",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "eCommerce Order Activity (MERCHANT_COMMENT)",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "ecom/order"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order_note",
+      "routes": [
+        "/wc/v3/orders/{parentId}/notes"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "ecomOrderActivity",
+      "routes": [
+        "eCommerce Orders API"
+      ],
+      "confidence": "high"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Orders",
+    "endpoint": "POST /ecom/v1/orders/{orderId}/activities/add",
+    "writerId": null,
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "follow-up-write-after-import",
+      "severity": "blocker",
+      "summary": "Order.activities[] is read-only on Create/Import Order — a merchant note can NEVER ride the order import payload. It must be a separate Add Activities call AFTER Import Order creates the order, using the crosswalked Wix order id."
+    },
+    {
+      "code": "timestamps-not-backdatable",
+      "severity": "warning",
+      "summary": "Add Activities stamps authorEmail and createdDate at call time (both read-only on the activity) — the activity will show the migration identity and migration date, and cannot be backdated to the source note's author/timestamp. If provenance matters, prefix the source author and original date into merchantComment.message text. VERIFIED LIVE 2026-08-16: the created activity came back with createdDate = the call instant and authorEmail = the LOGIN EMAIL BEHIND THE MIGRATION TOKEN (not the site owner, not a service identity) — so every migrated note is publicly attributed in the dashboard to whoever minted the token. Say so in the execution plan; a partner-run migration will otherwise stamp the partner's address across the merchant's order history."
+    },
+    {
+      "code": "order-placed-activity-precedes-the-note",
+      "severity": "info",
+      "summary": "VERIFIED LIVE 2026-08-16: Import Order auto-creates one ORDER_PLACED activity on every imported order before any note is added, so activities[] is never empty and a merchant note is always at index >= 1. Readback assertions must locate the note by activityType MERCHANT_COMMENT, not by activities[0]."
+    },
+    {
+      "code": "commingled-source-notes",
+      "severity": "warning",
+      "summary": "On the source side, a plugin's note is a genuine WooCommerce order note commingled with ALL other order notes (system-generated and other plugins') at /wc/v3/orders/{id}/notes — no meta key or note-type marker isolates it. Selecting which notes to migrate requires content inspection at import time, not just the read channel."
+    },
+    {
+      "code": "message-cap-5000",
+      "severity": "warning",
+      "summary": "merchantComment.message is 1–5000 chars. Longer source notes (or notes bloated by the provenance prefix) must be truncated or split into multiple activities; record any truncation in the migration ledger."
+    }
+  ],
+  "mappingGuidance": [
+    "source order notes (including payment-gateway plugin notes) map to eCom order activities — POST /ecom/v1/orders/{orderId}/activities/add with activityType MERCHANT_COMMENT and merchantComment.message (max 5000 chars) — called as a follow-up write AFTER Import Order creates the order.",
+    "Sequencing: import the order first (ecom/order via importOrder), resolve the Wix order id from the crosswalk, then add activities. Add Activities is currently documented to support MERCHANT_COMMENT only; up to 300 activities per request, but each request targets a single order.",
+    "Author and timestamp are stamped at call time and cannot be backdated. Preserve provenance inside the message text, e.g. '[source note — {author}, {original ISO date}] {note text}', keeping the total within 5000 chars.",
+    "Source notes are commingled with system and other plugins' notes on the source order — inspect note content at import time to decide which notes carry over; do not blindly replay every source order note.",
+    "No exported writer exists yet in rp-target-wix/lib/wix-writers.js (writerId null) — plan this as a direct REST call in the generated import script until a writer is added."
+  ],
+  "setupRequirements": [
+    "Order crosswalk (source order id -> Wix order id) populated by the order import before any activity write."
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/add-activities",
+      "note": "Add Activities schema, markdown fetched 2026-08-16: POST https://www.wixapis.com/ecom/v1/orders/{orderId}/activities/add; up to 300 activities per request; orderActivities.activityType required; currently supports MERCHANT_COMMENT only; merchantComment.message minLength 1 / maxLength 5000; activity authorEmail and createdDate are read-only (stamped at call time)."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/orders/order-object",
+      "note": "Order object page (read 2026-08-16): activities (Array<Activity>) confirmed on the Order object; read-only on Create/Import Order per the import-order request schema (activities absent from the writable request body)."
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-target-wix/domains/ecom/entities/order.json",
+      "note": "Sibling entity's mappingGuidance records the same activities follow-up write verified live 2026-08-12; this entity stays verification: docs until a run promotes it directly under its own capability."
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/capabilities-pending-decision.json",
+      "note": "The plugin-rest-child read channel supplies commerce.payment-gateway-notes, which this entity resolves."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: POST /ecom/v1/orders/{orderId}/activities/add created a MERCHANT_COMMENT that GET returned verbatim, including a caller-supplied source-author/date prefix. Wix assigned the activity ID and current createdDate and recorded the token holder's login email as authorEmail. Probe records were deleted after verification."
+    }
+  ],
+  "notes": "Authored 2026-08-16. Promoted to verified-live 2026-08-16 by an import-then-add-activity probe under this entity's own capability on an anonymized verification environment. writerId stays null — the direct-REST plan is unchanged; a dedicated writer in rp-target-wix/lib/wix-writers.js is still the open gap."
+}

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

@@ -0,0 +1,191 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-payment",
+  "displayName": "eCommerce Order Payment",
+  "capability": "commerce.order-payments",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "eCommerce Order Transactions",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "objectPageException": "The Order Transactions API is not modelled as a fetchable object with its own '…-object' reference page. Its reference tree exposes an introduction, terminology, sample flows and the methods (Add Payments, List Transactions For Single/Multiple Orders, Update Payment Status), with no object page for Payment or OrderTransactions. Confirmed by a ranked SearchWixRESTDocumentation query for the order-transactions object reference on 2026-09-03, which returned the methods and articles cited in evidence[] and no object page. The field shape here is taken from the Add Payments method schema.",
+  "dependsOn": [
+    "ecom/order"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order_payment_meta",
+      "routes": [
+        "/wc/v3/orders/{id}"
+      ],
+      "confidence": "high"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "eCom Order Transactions",
+    "endpoint": "GET /ecom/v1/payments/orders/{orderId} then POST /ecom/v1/payments/orders/{orderId}/add-payment",
+    "writerId": "writeOrderPayment",
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [],
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "existenceGate": {
+    "summary": "A payment record is written only when the source supplies BOTH a positive amount and a paid date. An order total, a gateway-shaped key, an order status, and a transaction reference are each insufficient.",
+    "required": [
+      "a source amount that parses and is greater than zero",
+      "a source paid date"
+    ],
+    "neverSufficient": [
+      "the order total on its own",
+      "the order status on its own",
+      "a resolved provider transaction reference on its own"
+    ],
+    "outcomes": [
+      "payment-written",
+      "payment-reconciled-existing",
+      "payment-not-written-no-amount",
+      "payment-not-written-no-paid-date",
+      "payment-not-written-multi-payment",
+      "payment-not-written-currency-mismatch",
+      "payment-reconciliation-ambiguous",
+      "payment-target-read-failed",
+      "payment-failed"
+    ]
+  },
+  "fieldMapping": [
+    {
+      "target": "amount.amount",
+      "rule": "Required. Absent, unparseable or non-positive means no payment record."
+    },
+    {
+      "target": "createdDate",
+      "rule": "Required, from the source paid date. Never defaulted to the order date or migration day: omitting it makes the API stamp the current time."
+    },
+    {
+      "target": "status",
+      "rule": "Literal APPROVED, written only after the existence gate passes. PAYMENT-LEVEL field.",
+      "limit": null
+    },
+    {
+      "target": "regularPaymentDetails.paymentMethodName.userDefinedName.custom",
+      "rule": "Source method title, else method slug. Omitted when absent; never invented.",
+      "limit": 150
+    },
+    {
+      "target": "regularPaymentDetails.providerTransactionId",
+      "rule": "Only a defensibly attributed reference. Omitted and counted when unresolved; never truncated.",
+      "limit": 100
+    },
+    {
+      "target": "regularPaymentDetails.offlinePayment",
+      "rule": "From verified method classification: true for known offline, false for known online, OMITTED and counted when unknown. Omission is not a synonym for false."
+    },
+    {
+      "target": "regularPaymentDetails.creditCardDetails.lastFourDigits",
+      "rule": "Only from a compatible verified gateway field. Whole object omitted when absent or incompatible.",
+      "limit": 4
+    },
+    {
+      "target": "regularPaymentDetails.creditCardDetails.brand",
+      "rule": "Only from a compatible verified gateway field.",
+      "limit": 100
+    },
+    {
+      "target": "regularPaymentDetails.savedPaymentMethod",
+      "rule": "NEVER SET. Writable, but no reusable credential can accompany it, so setting it asserts a charging agreement that does not exist."
+    },
+    {
+      "target": "refundDisabled",
+      "rule": "Not set, pending verification that it does not block an externalRefund write."
+    },
+    {
+      "target": "currency",
+      "rule": "No such field exists on a payment. Wix derives it from the order, so a source/target currency mismatch stops the payment write and is reported."
+    }
+  ],
+  "pitfalls": [
+    {
+      "code": "order-total-is-not-payment-evidence",
+      "severity": "blocker",
+      "summary": "An order total exists on orders that were never paid. VERIFIED LIVE on a production WooCommerce store: `_order_total` is present on cancelled and failed orders, which almost never carry a paid date. Creating an APPROVED payment wherever a total exists would mint approved payments for unpaid orders, overstating revenue in a more authoritative-looking place than the bug it replaced. Require a paid date."
+    },
+    {
+      "code": "status-allowlist-is-not-the-gate",
+      "severity": "blocker",
+      "summary": "Do NOT gate on an allowlist of 'paid' order statuses. VERIFIED LIVE: a store's terminal paid state can be `wc-processing` while `wc-completed` is nearly unused, so an allowlist keyed on 'completed' would import almost none of the paid orders. Status semantics are per-store. Status is a conflict/report axis only: a paid date on a cancelled order is preserved and the contradiction counted, and an unfamiliar status never blocks a real paid date."
+    },
+    {
+      "code": "status-is-a-payment-level-field",
+      "severity": "warning",
+      "summary": "SCHEMA DRIFT FOUND 2026-09-03 while re-checking the live Add Payments schema. `status` is a payment-level field, sibling to `amount` and `createdDate`, and that is the current field. The previous writer nested it inside `regularPaymentDetails`, which the schema still carries as a DEPRECATED field marked as replaced by the top-level one -- so the earlier claim that those requests \"asserted nothing about status\" was too absolute: they used the deprecated shape, whose behaviour is not guaranteed to persist. Write the top-level field. Pinned by tests/target-wix/order-payment-field-mapping-test.js."
+    },
+    {
+      "code": "reference-not-returned-for-offline-payments",
+      "severity": "info",
+      "summary": "DOCS SAY one thing and the API does another. The schema states that `providerTransactionId` and `gatewayTransactionId` are \"not returned for offline payments\". LIVE-VERIFIED 2026-09-04 on a disposable site: an offline payment written WITH a `providerTransactionId` read it straight back. So the documented behaviour is wrong, or at least not universal. Reconciliation for offline payments matches on the fact fingerprint rather than the reference, which works either way -- it was built for the documented behaviour and is now simply belt-and-braces. Do NOT rely on the reference being absent, and do not treat its presence as drift."
+    },
+    {
+      "code": "payment-status-recalculates-asynchronously",
+      "severity": "warning",
+      "summary": "SCHEMA-DOCUMENTED: the order's `paymentStatus` is recalculated asynchronously after Add Payments, so reading the order immediately afterward may still show the previous status. Verification must not assert on `order.paymentStatus` right after the write."
+    },
+    {
+      "code": "duplicate-reference-fails-the-whole-call",
+      "severity": "blocker",
+      "summary": "SCHEMA-DOCUMENTED: if any payment's external transaction id already exists on the order, the ENTIRE Add Payments call fails and no payments are added. This is why the order's existing payments are read and reconciled by identity before every create, and why a failed target read resolves to `payment-target-read-failed` rather than to permission to create."
+    },
+    {
+      "code": "reconcile-by-identity-never-by-position",
+      "severity": "blocker",
+      "summary": "The replaced implementation selected a payment with `(payments || []).find((p) => !p.refundDisabled)?.id`. That is identity-free: it matches an unrelated record, including one the merchant created by hand in the Business Manager, and would attach a refund to the wrong payment. Match by provider transaction reference when one was defensibly sourced, otherwise by an exact fingerprint of amount, paid date, normalized method name, offline marker and card display fields. Exactly one match reconciles; more than one is ambiguous and prohibits creation."
+    },
+    {
+      "code": "paid-date-timezone-is-a-real-loss",
+      "severity": "warning",
+      "summary": "WooCommerce records the moment an order was paid TWICE: the `_gmt` sibling in universal time, and the plain field on the shop's wall clock with the zone stripped off. They are one payment described in two clocks, not two events, so the loss is per stamp and one shop offset cannot be correct for both. A paid stamp arrives in three shapes -- an epoch stamp, a full ISO instant, and a bare 'YYYY-MM-DD HH:MM:SS' wall-clock string with no zone; only the first two are unambiguous, and only the third is affected by any of this. Declare the clock each source key is written in: a key that is universal by the source schema's definition takes NO shop offset, so supplying the site's UTC offset leaves it exactly where it stands, and a key on the shop's wall clock takes the offset when one is known. A wall-clock stamp whose clock nobody has supplied is read as UTC and COUNTED as `paid-date-timezone-assumed` against that field, because silently shifting a payment by the shop's offset is a fidelity loss a merchant may discover later while reconciling a tax period; never invent the offset from the shop's address, and never express 'already universal' as an offset of zero, which asserts a measurement about the shop in place of a definition about the key."
+    },
+    {
+      "code": "data-extension-schema-read-propagates",
+      "severity": "warning",
+      "summary": "LIVE-VERIFIED 2026-09-04: an immediate List after a successful schema create reported the new fields ABSENT, while an order PATCH moments later accepted values for them -- which the API only allows when the schema contains them. The write had landed; the read was stale. Verifying once therefore produces a false 'not verified after write' on every fresh provision, which would block dependent writers. The re-read retries with backoff before believing a negative result."
+    }
+  ],
+  "mappingGuidance": [
+    "Run the existence gate before anything else. Ineligible orders must never reach the write path, which also keeps target reads proportional to evidenced payments rather than to the whole order population.",
+    "Resolve the transaction reference, card display fields and offline classification through the source-side registry, not from a payment-method slug: the slug names the checkout plugin, not necessarily the processor behind it.",
+    "One payment record per order in phase 1. A source exposing more than one distinct payment amount is reported as `payment-not-written-multi-payment`, never summed into one record.",
+    "Report the payment outcome for every source order. The mutually exclusive outcomes must sum to the discovered source-order population on every run, so a clean re-run reports reconciled records rather than disguising them as skips."
+  ],
+  "setupRequirements": [],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/order-transactions/add-payments",
+      "note": "Full method schema re-checked 2026-09-03. Established: status is payment-level; createdDate is settable and defaults to now when omitted; providerTransactionId max 100; userDefinedName.custom max 150; lastFourDigits max 4; brand max 100; 50 payments per call; 100 payments per order; duplicate external transaction id fails the entire call; order paymentStatus recalculates asynchronously."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-transactions/list-transactions-for-single-order",
+      "note": "The mandatory pre-write reconciliation read."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Live post-meta survey behind the existence gate and the status-allowlist refutation."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/orders/order-transactions/introduction",
+      "note": "Introduction, read 2026-09-03. Confirms two behaviours this entity depends on, in Wix's own words: 'The Order Transactions API records payments and refunds. It doesn't charge or refund funds. Adding a payment record or updating a payment status has no effect on the actual money movement.' And: 'After a payment record is added or updated, the order's paymentStatus is recalculated asynchronously. Reading the order immediately afterward may still show the previous payment status.'"
+    }
+  ]
+}