@wix/agent-skills 1.33.0 → 1.34.0

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

@@ -0,0 +1,182 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "discount-rule",
+  "displayName": "eCommerce Discount Rule (\"Automatic Discounts\" in the dashboard)",
+  "capability": "commerce.discount-rules",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "DiscountRule",
+    "verifiedFqdn": "wix.ecom.discounts.v1.discount_rule",
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "stores/product",
+    "stores/category"
+  ],
+  "blockedSourceDependencies": [
+    {
+      "sourceEntityRef": "plugin.woo-discount-rules.discount-rule-definition",
+      "degradedField": "rule-definition",
+      "pitfallCode": "rule-definitions-via-bridge-plugin-not-rest",
+      "degradation": "warning"
+    }
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "discount-rule-definition",
+      "sourcePlugin": "woo-discount-rules",
+      "routes": [],
+      "confidence": "medium",
+      "note": "No REST route to the wp-admin settings page itself, but the underlying wdr_rules table is directly readable via wix-wp-plugin-v2's discover-structure/query-structure -- VERIFIED LIVE 2026-08-28 against an anonymized live source. See the plugin profile's db-only entity and its blocked[].fulfillment."
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Discount Rules",
+    "endpoint": "POST /ecom/v1/discount-rules",
+    "writerId": "createDiscountRule",
+    "verification": "verified-live",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    {
+      "classification": "cms",
+      "when": "The source rule's trigger/effect combination cannot be expressed by DiscountRule's trigger/discount model (e.g. a shape Wix genuinely has no primitive for) — record as a mapping gap with the specific unsupported combination, do not approximate silently."
+    }
+  ],
+  "reliability": {
+    "status": "partially-reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "scope-id-must-follow-wix-own-prefix-convention-or-the-rule-is-dashboard-uneditable",
+      "severity": "blocker",
+      "summary": "`scopes[].id` accepts ANY non-empty string server-side (create succeeds with an arbitrary value like `\"stores-catalog\"`), but the merchant dashboard's own Automatic Discounts editor only recognizes the id patterns Wix's own tooling generates: `all_<catalogAppId>` (storewide), `specific_<catalogAppId>` (named products, id + catalogItemIds), `collections_<catalogAppId>` (CUSTOM_FILTER, a collection). VERIFIED LIVE 2026-08-29 in anonymized live verification: a rule created with `scopes[].id: \"stores-catalog\"` shows in the dashboard as created by a third-party integration with NO edit option at all -- confirmed by direct comparison via Get Discount Rule against a dashboard-created rule in the same anonymized verification environment, whose only structural difference was this id (`all_215238eb-22a5-4c36-9e7b-e7c08025e04e`) plus a populated `settings` object (see the settings-object pitfall below). This defeats any placeholder-rule strategy that relies on the merchant reconfiguring the rule afterward in the dashboard -- always use the real `all_`/`specific_`/`collections_` prefix, never an arbitrary caller-assigned id, even though the API accepts one.",
+      "unverified": false
+    },
+    {
+      "code": "settings-and-activeTimeInfo-should-be-populated-on-create",
+      "severity": "blocker",
+      "summary": "`settings.indexOptIn` and `activeTimeInfo.start` are both omittable server-side (create succeeds with neither), but every dashboard-created rule observed live carries `settings.indexOptIn: true` and a populated `activeTimeInfo.start` even when the caller never asked for a start date -- confirmed by the Wix skills doc's own \"Settings\" section (`{appliesTo: \"ALL_ITEMS\", indexOptIn: true}` verbatim) and its \"Date handling\" table (`startDate` empty -> default to current time, never omit). Missed in the first TWO live-fix passes in anonymized live verification (2026-08-29) -- both times the dashboard-editability bug looked fully explained by the scope-id/quantity-range findings alone, but this was a third, independently real gap sitting underneath them. Always set `settings: {appliesTo: \"ALL_ITEMS\", indexOptIn: true}` AND `activeTimeInfo: {start: <now, ISO 8601>}` on create -- never omit either just because the API accepts the omission.",
+      "unverified": false
+    },
+    {
+      "code": "automatic-discounts-is-a-dashboard-label-for-discount-rules",
+      "severity": "info",
+      "summary": "The Wix dashboard calls this feature 'Automatic Discounts'; the API/data model name is DiscountRule (`ecom/v1/discount-rules`). Distinct from the Coupons API (stores/coupon.json) — coupons need a customer-entered code, discount rules apply automatically when their trigger is met. Do not conflate the two when a source plugin (e.g. WooCommerce Discount Rules) models automatic, no-code discounting."
+    },
+    {
+      "code": "only-one-discount-per-rule",
+      "severity": "warning",
+      "summary": "Per dev.wix.com: 'Currently, only 1 discount can be defined per discount rule.' A source rule with multiple stacked effects needs one Wix DiscountRule per effect, not one rule with a list."
+    },
+    {
+      "code": "cumulative-tiered-discount-needs-one-rule-per-tier-no-clean-solution",
+      "severity": "blocker",
+      "summary": "SUPERSEDED IN PART 2026-08-31 -- see bounded-quantity-bands-need-a-custom-trigger-spi below for a clean solution via the Custom Discount Triggers service plugin (bands become mutually exclusive, nothing stacks). The trade-off described here still applies whenever you are restricted to NATIVE triggers only.\n\nA source cumulative/tiered quantity discount (e.g. WooCommerce Discount Rules' bulk_adjustments: 1-5 units -> 5% off, 6-10 -> 10%, 11-15 -> 15%, ...) has no single-rule Wix equivalent (only-one-discount-per-rule, above), AND every multi-rule approach has a real downside -- there is no clean fix, only a tradeoff a human must choose:\n(a) BOUNDED (`itemQuantityRange: {from, to}`, both inclusive -- VERIFIED LIVE the field accepts both, not from-only as the truncated docs example suggested): ranges are non-overlapping by construction (correct math, no stacking), but VERIFIED LIVE 2026-08-29 the merchant dashboard's Automatic Discounts editor cannot render a bounded range at all -- it shows EVERY such rule as created by a third-party integration with no edit option, the same failure as the scope-id pitfall, not a coincidence.\n(b) OPEN-ENDED (`itemQuantityRange: {from}` only, one rule per tier's minimum): fully dashboard-editable (VERIFIED LIVE), but the tiers are not mutually exclusive once activated -- past the highest threshold every lower tier's trigger is also true and Wix stacks them (e.g. at 21+ items: 5+10+15+20+25 = 75% off, not 25%), a real compounding-discount bug once live, not just an approximation.\nDEFAULT SUPERSEDED 2026-08-31. The old default was (b) open-ended, on the reasoning that every tier imports `active: false` so a merchant would consolidate before activating, and that a Custom Discount Trigger was 'out of scope for a data migration'. BOTH HALVES WERE WRONG. Relying on the import being inactive is not a control — it only defers the bug to whoever flips the switch, and 5+10+15+20+25 = 75% off is then live. And the service plugin is in scope: it is the sanctioned rung 3 of the escalation ladder, built with the Wix CLI as an app extension, implemented and verified end to end against live carts. CURRENT DEFAULT: express bounded bands through a Custom Discount Trigger service plugin, which answers yes/no per cart so exactly one tier can match. See bounded-quantity-bands-need-a-custom-trigger-spi below and domains/SERVICE-PLUGINS.md. Options (a) and (b) above remain accurate descriptions of the NATIVE-ONLY trade-off and are kept for the case where a service plugin is genuinely unavailable — but neither is the default any more, and choosing (b) means accepting a live compounding-discount bug."
+    },
+    {
+      "code": "trigger-type-and-discount-type-are-each-a-closed-enum",
+      "severity": "warning",
+      "summary": "trigger.triggerType: AND | SUBTOTAL_RANGE | ITEM_QUANTITY_RANGE | CUSTOM | OR | CUSTOMER_ELIGIBILITY. discounts.values[].discountType: PERCENTAGE | FIXED_AMOUNT | FIXED_PRICE | QUANTITY_BASED. Both enums read live off the server's own UnrecognizedEnumValidator error by POSTing a bogus value -- do that instead of trusting a doc page. CORRECTION 2026-08-31: an earlier version of this pitfall said a true 'buy X get Y' where X and Y differ has no equivalent. THAT IS WRONG -- see buy-x-get-y-is-supported-but-undocumented below. QUANTITY_BASED is only for '3 for $10'; BOGO lives on targetType, not discountType, which is why it looked absent.",
+      "unverified": false
+    },
+    {
+      "code": "scope-targets-a-real-catalog-item-id-not-a-source-id",
+      "severity": "blocker",
+      "summary": "`scopes[].catalogItemFilter.catalogItemIds` takes Wix catalog item GUIDs (e.g. the migrated product's Wix product id from the product crosswalk), not the source WooCommerce product id. Resolve via the product crosswalk before building the scope, the same as category/tag assignment elsewhere in this pipeline. Omitting scopes (or passing none) applies the rule storewide."
+    },
+    {
+      "code": "rule-definitions-via-bridge-plugin-not-rest",
+      "severity": "warning",
+      "summary": "The source rule configuration has no REST route at all (wp-admin/admin.php?page=woo_discount_rules renders it, with no API) -- it is read via wix-wp-plugin-v2's discover-structure/query-structure against the plugin's own wdr_rules table instead, VERIFIED LIVE 2026-08-28 against an anonymized live source. This requires the site owner to have installed wix-wp-plugin-v2 (see plugins/wix-wp-plugin-v2/README.md) -- a source with only a standard WooCommerce REST credential and no bridge plugin installed cannot migrate this entity's data at all, only reconfigure it manually in Wix."
+    },
+    {
+      "code": "buy-x-get-y-is-supported-but-undocumented",
+      "severity": "blocker",
+      "summary": "Wix DOES support buy-X-get-a-DIFFERENT-Y. Two earlier passes of this file and an earlier research pass concluded it does not, and both were WRONG. VERIFIED LIVE 2026-08-31: discounts.values[].targetType accepts [UNDEFINED, SPECIFIC_ITEMS, BUY_X_GET_Y]. Payload is buyXGetYInfo: {customerBuys: {scopes[], minimumQuantity | minimumSpend}, customerGets: {scopes[], quantity}, limit?}. WHY IT LOOKS UNSUPPORTED, so the next reader does not repeat the mistake: (a) buyXGetYInfo appears NOWHERE in the published Create Discount Rule method schema; (b) the docs' one 'Create Buy X Get Y Discount Rule' example is a body that returns a bare HTTP 500, because it shows only targetType/discountType/fixedPrice and omits buyXGetYInfo entirely; (c) the server's error text says 'buyXGetYInfo.customerBuy.condition' -- SINGULAR, which is the protobuf type name, while the actual field is customerBuys (PLURAL). The shape is only visible via SearchWixAPISpec's component schemas: getResourceSchemaByUrl(docsUrl).components.schemas['com.wix.ecom.discounts.BuyXGetYInfo']. RULE: when a Wix method 500s on its own documented example, inspect the component schemas before concluding a capability is absent."
+    },
+    {
+      "code": "offer-string-is-the-machine-readable-dashboard-editability-test",
+      "severity": "blocker",
+      "summary": "The server computes a human-readable `offer` summary on every discount rule and returns it on create/get/query. An EMPTY STRING means the merchant dashboard cannot render the rule and shows it as created by a third-party integration with no edit option. THE TEST IS ONE-WAY: a populated `offer` does NOT prove the rule is editable — see the scope note below. VERIFIED LIVE 2026-08-31 by creating throwaway rules and deleting them, and corroborated by a merchant independently reporting exactly the rule whose offer was empty.\n\nSCOPE OF THE TEST -- READ THIS BEFORE TRUSTING IT. `offer` reflects the DISCOUNT and its SCOPE only. It is TRIGGER-BLIND: verified live 2026-08-31 that a rule with no trigger at all, one with a bounded itemQuantityRange {from:6,to:10}, and one with subtotalRange {from:500} ALL return the byte-identical offer '10% off\\nAll products'. So an empty offer proves a rendering problem, but a POPULATED offer does NOT prove the trigger renders. Use this test for scope/target shapes (where it is proven). Do NOT use it to clear the cumulative-tiered-discount pitfall's bounded-range claim -- that one is about the trigger, and only a human opening the dashboard can currently settle it."
+    },
+    {
+      "code": "buyxgety-renders-only-with-exactly-one-catalog-item-scope",
+      "severity": "blocker",
+      "summary": "Inside buyXGetYInfo.customerBuys.scopes, only a SINGLE CATALOG_ITEM scope renders in the dashboard. VERIFIED LIVE 2026-08-31 on one site, each case created then deleted, judged by the `offer` string: 1 x CATALOG_ITEM with <=50 explicit catalogItemIds -> offer rendered, EDITABLE. 1 x CATALOG_ITEM storewide (all_<appId>, empty catalogItemIds) -> rendered, EDITABLE. 2 x CATALOG_ITEM scopes -> offer '', NOT editable. 1 x CUSTOM_FILTER (a Stores category) -> offer '', NOT editable. 3 x CUSTOM_FILTER -> offer '', NOT editable. So more than one scope, or ANY category/collection scope, breaks rendering regardless of count. CONSEQUENCE, and it is a real trade-off with no clean answer: catalogItemIds caps at 50 per scope, so a source rule whose trigger covers MORE than 50 products cannot be both faithful and dashboard-editable. Choose explicitly and record which: (a) keep the category/CUSTOM_FILTER scope -- faithful, uneditable; (b) enumerate <=50 product ids -- editable, silently drops the rest; (c) go storewide -- editable, triggers far wider than the source. Never pick one silently."
+    },
+    {
+      "code": "specificiteminfo-belongs-on-the-discount-value-not-the-rule",
+      "severity": "blocker",
+      "summary": "specificItemsInfo goes on discounts.values[0], NOT on the discountRule object. Putting it on the rule passes request validation and then returns a bare HTTP 500 with an empty body and no field violation -- there is nothing in the response to point at the mistake. VERIFIED LIVE 2026-08-30 (cost several probe rounds). Same class of failure as omitting settings.appliesTo: the 500 is the ONLY signal, so when a discount-rule create 500s, suspect misplaced or missing sub-objects before anything else."
+    },
+    {
+      "code": "carry-the-source-rule-name-and-active-flag-verbatim",
+      "severity": "warning",
+      "summary": "Import the source rule's own name, with no migration prefix or tag -- a merchant comparing the two systems side by side must see the same string in both. `name` is capped at 50 characters, so truncate only when the source title genuinely exceeds it (Hebrew and other non-Latin titles hit this sooner than they look). Where one source rule legitimately becomes several Wix rules (see cumulative-tiered-discount...), suffix the source name with the distinguishing bound rather than renaming it. Likewise mirror the source rule's enabled/disabled flag into `active` instead of importing everything inactive by default: a promotion running at source should run at the destination. TWO CASES WHERE MIRRORING IS UNSAFE and the importer must import inactive and say so loudly: (1) the source rule is gated on something Wix cannot express -- a cart coupon code is the common one -- so an 'active' import applies unconditionally and gives the discount to everyone; (2) one source rule expanded into several open-ended tiers, which stack once active."
+    },
+    {
+      "code": "bounded-quantity-bands-need-a-custom-trigger-spi",
+      "severity": "blocker",
+      "summary": "RESOLVES the cumulative-tiered-discount pitfall's 'no clean solution'. A source bulk/tiered discount (1-5 -> 5%, 6-10 -> 10%, 11-15 -> 15%, ...) has a clean Wix mapping after all, but not through a native trigger: implement the Custom Discount Triggers SERVICE PLUGIN and give each tier its own bounded band. Each tier becomes one DiscountRule with trigger {triggerType:'CUSTOM', customTrigger:{id:'<band id>', appId:'<your app>'}}, and the plugin answers a plain yes/no per cart -- so bands are mutually exclusive, nothing stacks, and no bounded itemQuantityRange is needed. IMPLEMENTED, DEPLOYED AND VERIFIED END TO END AGAINST LIVE CARTS 2026-08-31 (with only the 6-10 band active: 3 units -> no discount, 7 units -> exactly 10% off, 11 units -> NO discount. The 11-unit case is the proof, because the old open-ended shape would have discounted it too — design the verification around the input where old and new behaviour DISAGREE, or a passing test proves nothing). A complete, copy-pasteable implementation is in domains/SERVICE-PLUGINS.md.\n\nDESIGN THAT MADE IT CHEAP: encode the band in the trigger id ('bulk-qty-6-10', 'bulk-qty-21-plus') and parse it in getEligibleTriggers, so re-cutting a tier is a discount-rule edit with NO plugin redeploy; listTriggers only feeds the dashboard dropdown. Count UNITS not lines (sum lineItems[].quantity) to match WooCommerce's product_cumulative operator. Treat an unparseable id as NOT eligible -- a permissive default silently discounts every cart.\n\nCOST, so this is not chosen lightly: it needs a Wix CLI app project (`wix generate` -> Service Plugin -> Ecom Discount Triggers), and `wix release` to deploy -- which ALSO PUBLISHES THE SITE. The plugin becomes permanent production infrastructure: uninstall the app and every tier rule pointing at its triggers stops resolving. Worth it for a real tiered promotion, not for a disabled sample rule.\n\nSEE ALSO rp-target-wix/domains/SERVICE-PLUGINS.md — the escalation rule, the honest cost list (an app, hosting, a 3-second budget, permanent production infrastructure, and the fact that `wix release` also PUBLISHES THE SITE), a full worked example including the SDK's inbound-only id -> _id rename, and the catalog of all 25 Wix service plugins with a per-plugin judgment on whether it could close a migration gap."
+    },
+    {
+      "code": "sdk-renames-rest-id-to-underscore-id-in-service-plugins",
+      "severity": "warning",
+      "summary": "When implementing an SPI through @wix/ecom/service-plugins, the SDK types rename the REST `id` field to `_id` -- and only on the inbound side. For Custom Discount Triggers, VERIFIED 2026-08-31 against the shipped .d.ts: request is triggers[].customTrigger._id, listTriggers returns customTriggers[]._id, but getEligibleTriggers returns eligibleTriggers[].customTriggerId (NOT renamed) and LineItem.quantity is unchanged. A correct handler therefore looks internally inconsistent. Writing `id` on the list side compiles clean in plain JS and silently returns a trigger list Wix cannot match to any rule -- the discount never applies and nothing errors. Read node_modules/@wix/auto_sdk_ecom_custom-triggers/build/cjs/interfaces-*.d.ts rather than the REST docs, and typecheck (astro check / tsc) before releasing."
+    }
+  ],
+  "mappingGuidance": [
+    "ESCALATION LADDER for a source discount shape that does not obviously fit. Work it in order and do not skip a rung. (1) NATIVE PRIMITIVE FIRST, ALWAYS — and confirm what native actually offers by reading the live enum off the server rather than a doc page: POST a bogus value and let UnrecognizedEnumValidator list the real members. targetType accepts BUY_X_GET_Y, which two earlier passes of this file declared impossible because it is absent from the published method schema and the docs' own example for it 500s (see buy-x-get-y-is-supported-but-undocumented). (2) NATIVE BUT MERELY AWKWARD STILL BEATS INFRASTRUCTURE — an extra rule per tier, more configuration, a field the merchant re-enters. AWKWARD IS NOT THE SAME AS INEXACT, AND THE LINE IS WHAT A CUSTOMER PAYS: ask whether the shape changes WHO QUALIFIES or WHAT THEY ARE CHARGED. A widened scope (e.g. variation ids resolving up to their parent product, so every variant now qualifies) and a lossy field both FAIL that test — they are approximations, not awkwardness, and they belong at (4) with the gap, not here. An earlier version of this guidance listed a widened scope as a preferred native fallback; that was wrong and it contradicted (4). (3) ONLY IF WIX HAS NO PRIMITIVE for a condition the source depends on, build a CUSTOM DISCOUNT TRIGGER service plugin: Wix calls your endpoint on every cart change and you answer yes/no per trigger, so any condition you can compute from the cart becomes expressible. Docs: https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/introduction Add it with the CLI: https://dev.wix.com/docs/build-apps/develop-your-app/develop-an-app-with-the-cli/supported-extensions/backend/service-plugins/add-service-plugin-extensions-with-the-wix-cli Full cost, caveats, a complete worked example and the catalog of all 25 Wix service plugins: rp-target-wix/domains/SERVICE-PLUGINS.md. (4) IF NEITHER WORKS IT IS A REAL GAP — and so is anything you had to approximate to make 'native' fit. Record it with the rule's exact values and say what changed. An approximated discount silently changes what customers are charged, which is worse than an absent one because an absent one is visible.",
+    "A trigger-less rule (`trigger` omitted) always applies — use this for a source rule with no minimum-spend/quantity condition.",
+    "SUBTOTAL_RANGE trigger maps a WooCommerce 'X% off orders over $Y' rule: trigger.subtotalRange.from = Y, no `to` needed for an open-ended minimum.",
+    "ITEM_QUANTITY_RANGE maps a simple buy-N-get-discount rule when the discount applies to the same items counted by the trigger. It supports a `to` bound (inclusive) as well as `from`, but VERIFIED LIVE `to` makes the dashboard treat the rule as third-party-created/uneditable -- see the cumulative-tiered-discount pitfall for the real tradeoff before choosing bounded vs. open-ended for a multi-tier discount.",
+    "Storewide (no product/category restriction) does NOT omit `scopes` -- VERIFIED LIVE 2026-08-29: a real dashboard-created storewide rule still carries `specificItemsInfo.scopes: [{id: \"all_<catalogAppId>\", type: \"CATALOG_ITEM\", catalogItemFilter: {catalogAppId}}]`. Always build the scope with the real `all_`/`specific_`/`collections_` id-prefix convention (see the scope-id pitfall above) even for storewide; never omit `scopes` or invent an arbitrary `id`."
+  ],
+  "setupRequirements": [],
+  "objectPageException": "The Discount Rules API menu (dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction, checked 2026-08-12) lists only Create/Update/Delete/Get/Query — no dedicated '…-object' reference page exists for DiscountRule. The full field shape is sourced from Create Discount Rule's request/response schema instead.",
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/introduction"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/discount-rules/create-discount-rule"
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/skills/pricing-create-discount-rule"
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Live create and readback verification established that arbitrary scope IDs produce rules the dashboard treats as third-party-created and uneditable. Comparing against a dashboard-created rule isolated the supported scope-ID prefixes; see the scope-id-prefix pitfall."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Live create and readback verification compared bounded and open-ended cumulative quantity tiers. Bounded ranges were uneditable in the dashboard; open-ended tiers remained editable but overlap and can stack. See the cumulative-tiered-discount pitfall for the required migration decision."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Field-by-field live verification against dashboard-created rules established the complete create contract for dashboard editability: use the supported `all_`/`specific_`/`collections_` scope-ID prefix, `settings: {appliesTo, indexOptIn: true}`, and `activeTimeInfo.start`. Recreated rules carrying the complete field set were confirmed editable."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "2026-08-31: BUY_X_GET_Y confirmed supported and buyXGetYInfo's shape recovered from the API spec's component schemas; the `offer` empty-string rendering test discovered; and the one-CATALOG_ITEM-scope limit established across five scope shapes."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/business-solutions/e-commerce/extensions/discounts/custom-discount-triggers-integration-service-plugin/introduction",
+      "note": "Custom Discount Triggers service plugin — the sanctioned fallback when no native trigger expresses the source condition. Implemented live 2026-08-31; see domains/SERVICE-PLUGINS.md."
+    }
+  ]
+}

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

@@ -0,0 +1,129 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-applied-discount",
+  "displayName": "eCommerce Order Applied Discount",
+  "capability": "commerce.applied-discounts",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "eCommerce Order Applied Discount",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "dependsOn": [
+    "stores/coupon"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "applied_discount",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "high"
+    },
+    {
+      "sourceSystem": "wix",
+      "sourceEntity": "ecomOrderAppliedDiscount",
+      "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
+  },
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "historical-fact-not-live-rule",
+      "severity": "warning",
+      "summary": "Applied discounts import as historical fact via the merchantDiscount variant — Wix never re-evaluates them as live discount rules, and Import Order stores all money values as-is without recalculating priceSummary. The mapper must therefore keep the source order's totals internally consistent itself; nothing on the Wix side reconciles appliedDiscounts against priceSummary.discount. VERIFIED LIVE 2026-08-16: an order carrying appliedDiscounts totalling 8.00 with priceSummary.total 22.00 on a 30.00 subtotal was stored exactly as sent — and a control order with the same appliedDiscounts but NO priceSummary.discount kept total == subtotal, proving Wix applies nothing."
+    },
+    {
+      "code": "merchant-discount-amount-must-be-object",
+      "severity": "blocker",
+      "summary": "merchantDiscount.amount is a Price OBJECT ({ amount: \"5.00\" }), not a bare decimal string. VERIFIED LIVE 2026-08-16: sending merchantDiscount.amount as the string \"5.00\" 400s with 'Expected an object'. Same for lineItemDiscounts[].totalDiscount."
+    },
+    {
+      "code": "applied-discounts-order-not-preserved",
+      "severity": "warning",
+      "summary": "The appliedDiscounts array comes back REORDERED — VERIFIED LIVE 2026-08-16: [GLOBAL, SPECIFIC_ITEMS, SHIPPING] was sent and [SPECIFIC_ITEMS, GLOBAL, SHIPPING] read back. Any verification or crosswalk pass must correlate entries by content (discountType + amount + description), never by array index. Server-assigned appliedDiscounts[].id is available for post-create correlation."
+    },
+    {
+      "code": "line-item-ids-are-client-settable",
+      "severity": "info",
+      "summary": "VERIFIED LIVE 2026-08-16: lineItems[].id accepts a client-supplied GUID and Import Order preserves it verbatim (create response and later GET both return the sent GUID). This is what makes the lineItemDiscounts[].id linkage resolvable inside a single payload — mint the line item GUIDs locally during the transform and reference them from appliedDiscounts[].lineItemDiscounts[]."
+    },
+    {
+      "code": "order-number-must-be-numeric",
+      "severity": "blocker",
+      "summary": "Order.number must be a NUMERIC string. VERIFIED LIVE 2026-08-16: a non-numeric number (e.g. an order-prefix plugin's 'ZZZ-PROBE-1') fails the whole Import Order call with a bare 400 { message: 'Not a numeric value' } and no field path — the least diagnosable error on this surface. Sources with prefixed/suffixed order numbers (WooCommerce Sequential Order Numbers and friends) must strip to digits and carry the original display number elsewhere."
+    },
+    {
+      "code": "rule-definitions-reconfigure-in-wix",
+      "severity": "warning",
+      "summary": "Only the applied-discount RECORDS on historical orders migrate. The discount rule DEFINITIONS (percentage/BOGO/tiered configuration) are plugin-owned config with no migration path — reconfigure them in Wix (native discount rules / coupons) and report them as reconfigure-in-wix, never as imported data."
+    },
+    {
+      "code": "line-item-discount-id-linkage",
+      "severity": "warning",
+      "summary": "appliedDiscounts[].lineItemDiscounts[].id must be the GUID of a line item in the SAME Import Order payload (docs: 'Line item GUID', maxItems 300). Source per-line-item discount rows (e.g. _wdr_discounts on order-item meta) must be joined to their line items before the write; a dangling id silently misattributes the discount."
+    },
+    {
+      "code": "merchant-discount-description-cap",
+      "severity": "warning",
+      "summary": "merchantDiscount is a one-of: either a predefined discountReason enum (UNSPECIFIED / EXCHANGED_ITEMS / BILLING_ADJUSTMENT — none fits a source plugin rule) or a free-text description capped at 200 chars. Source rule names/labels longer than 200 chars truncate; keep the full label in the migration ledger if it matters."
+    },
+    {
+      "code": "coupon-variant-verified-on-import-order",
+      "severity": "info",
+      "summary": "VERIFIED LIVE 2026-09-05 (fresh site): Import Order accepts `appliedDiscounts: [{ discountType: 'GLOBAL', coupon: { id, code, name, amount: { amount } } }]` naming a coupon created seconds earlier on the same site, and GET reads the entry back with the same id, code and amount; `priceSummary.discount` is stored as sent. Built by rp-target-wix/lib/order-applied-discount-build.js from the source order's coupon lines through the coupon crosswalk; a code the crosswalk cannot resolve produces no entry and an unresolved report line."
+    }
+  ],
+  "mappingGuidance": [
+    "source-plugin applied-discount records map to Order.appliedDiscounts[] with the merchantDiscount variant, written at import time on the eCom Import Order (or Create Order for live flows) payload.",
+    "Use the merchantDiscount one-of variant for discounts a source plugin computed and applied on the source site: description = source rule label (free text, max 200 chars), amount = the applied discount Price. Do NOT use the discountRule variant — its id is a Wix discount-rule GUID that does not exist for source-computed discounts — and do not use coupon unless the source discount genuinely was a coupon redemption (then it belongs to the coupon crosswalk instead).",
+    "These records are carried as historical fact only: Wix never re-evaluates them as live discount rules, and rule DEFINITIONS are reconfigure-in-wix, not migratable data.",
+    "Set discountType per record: GLOBAL for order-level discounts, SPECIFIC_ITEMS when the source recorded per-line-item amounts, SHIPPING for free/discounted shipping. For SPECIFIC_ITEMS, fill lineItemDiscounts[] with { id: <line item GUID in the same payload>, totalDiscount: <Price> } per affected line.",
+    "appliedDiscounts caps: maxItems 320 per order; lineItemDiscounts maxItems 300 per discount entry. Overflow is implausible for real orders but must fail loudly, not silently drop.",
+    "Written through the parent order payload (ecom/order) — never a standalone write; sequencing and crosswalk requirements are the parent order's (contacts first, catalog crosswalks resolved).",
+    "dependsOn stores/coupon is conditional, not universal: only use the coupon one-of variant (and need that crosswalk) when the source discount genuinely was a coupon-code redemption. The far more common merchantDiscount variant (a plugin-computed, source-specific discount) needs no crosswalk at all — do not require stores/coupon for every order, only the ones that actually redeemed a real coupon."
+  ],
+  "setupRequirements": [
+    "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: appliedDiscounts (array<AppliedDiscount>, maxItems 320) is writable on the request; each entry is a one-of coupon | merchantDiscount | discountRule; merchantDiscount = one-of discountReason enum (UNSPECIFIED/EXCHANGED_ITEMS/BILLING_ADJUSTMENT) or description (maxLength 200) plus amount (Price); discountType enum GLOBAL/SPECIFIC_ITEMS/SHIPPING; lineItemDiscounts[] (maxItems 300) carries { id: line item GUID, totalDiscount: Price }. Values stored as-is, no recalculation, no side effects."
+    },
+    {
+      "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): appliedDiscounts field confirmed on the Order object (Array<AppliedDiscount>)."
+    },
+    {
+      "type": "repo-research",
+      "path": "skills/wix-replatform/resources/rp-source-wordpress/plugins/capabilities-pending-decision.json",
+      "note": "commerce.applied-discounts pending-register entry (researched 2026-08-11, source-side _wdr_discounts shape verified against woo-discount-rules plugin source); resolved by this entity 2026-08-16."
+    },
+    {
+      "type": "live-run",
+      "path": "anonymized-live-verification",
+      "note": "Verified live: Import Order create and GET readback exercised all discountType variants. Sent values persisted, the server assigned appliedDiscounts[].id, and SPECIFIC_ITEMS linkage remained in lineItemDiscounts while lineItemIds[] and itemCombinations[] read back empty. merchantDiscount.amount must be an object, appliedDiscounts may be reordered on readback, and order.number must be numeric. 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 (see the live-run evidence entry); the merchantDiscount object-amount trap, the readback reordering, the client-settable line item GUID, and the numeric-order-number trap were all discovered by that probe, not by docs."
+}

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

@@ -0,0 +1,192 @@
+{
+  "schemaVersion": 1,
+  "domain": "ecom",
+  "entity": "order-invoice-document",
+  "displayName": "eCommerce Order Invoice Document (preserved reference)",
+  "capability": "commerce.order-invoice-documents",
+  "target": {
+    "classification": "native",
+    "nativeEntity": "eCommerce Order extended fields + Media Manager private file",
+    "verifiedFqdn": null,
+    "idPolicy": "server-assigned",
+    "crosswalkRequired": true
+  },
+  "objectPageException": "This is not a Wix object. It is a REFERENCE contract: the source invoice document is preserved as a private Media file and pointed at from two user-defined fields on the order. Wix exposes no historical-invoice entity to model, and the invoicing service is deliberately not called, so there is no object page to cite. The shapes come from the Import File, Generate File Download Url and Update Order method schemas in evidence[].",
+  "dependsOn": [
+    "ecom/order"
+  ],
+  "sourceAliases": [
+    {
+      "sourceSystem": "woocommerce",
+      "sourceEntity": "order_invoice_document",
+      "routes": [
+        "/wc/v3/orders"
+      ],
+      "confidence": "medium"
+    }
+  ],
+  "preferredWrite": {
+    "surface": "Media Manager (private) + eCom Orders extended fields",
+    "endpoint": "POST /site-media/v1/files/generate-upload-url (private), PUT the bytes to the signed uploadUrl, then PATCH /ecom/v1/orders/{order.id}",
+    "writerId": "preserveOrderInvoiceDocument",
+    "verification": "docs",
+    "importSafe": true,
+    "bulk": false
+  },
+  "fallbacks": [
+    {
+      "classification": "native",
+      "when": "Where the source holds an invoice NUMBER but no document, store the number alone as a reference and create nothing."
+    }
+  ],
+  "reliability": {
+    "status": "reliable",
+    "flags": []
+  },
+  "pitfalls": [
+    {
+      "code": "never-re-issue-a-historical-tax-document",
+      "severity": "blocker",
+      "summary": "Do NOT create, publish or re-issue a Wix invoice for a historical sale. Re-issuing mints a SECOND legal document for the same sale under a different number, and the original -- issued and numbered by whoever issued it -- remains the authoritative body. Separately, whether publishing an invoice emails the customer is undocumented in either direction, and on a multi-year store a wrong assumption emails thousands of customers an invoice for a sale they made years ago. The contract is NON-USE, provable by a route-level test rather than by a runtime probe: tests/target-wix/no-invoices-api-contract-test.js."
+    },
+    {
+      "code": "discovered-url-is-untrusted-input",
+      "severity": "blocker",
+      "summary": "A document URL read from source-site metadata is untrusted input that something is about to fetch. Classify before touching it: HTTPS only, no embedded credentials, port 443 only, no loopback/private/link-local address in either dotted or IPv4-mapped-IPv6 notation (`[::ffff:127.0.0.1]` classified SAFE until 2026-09-05 because Node canonicalizes it). LIMITS OF THIS CHECK, stated because the earlier wording promised more than the code does: it is LEXICAL. It does not resolve DNS and it does not follow or re-classify redirects, so a public hostname resolving to a private address, or redirecting to one, passes. Wix Media fetches the document server-side, so the request that would need bounding is not ours to bound. This rejects what is obviously internal; it is not SSRF protection, and a request-plan object that nothing executed used to sit here creating the opposite impression."
+    },
+    {
+      "code": "never-store-or-log-the-source-url",
+      "severity": "blocker",
+      "summary": "A hosted invoice URL is an unauthenticated bearer link whose query string can carry a token and whose filename can carry the customer's name and the invoice number. It is never written to a site-readable field, never logged, and never carried out of the import: the Import File RESPONSE echoes `sourceUrl`, so only the returned file `id` is kept. Media `displayName` is derived from the invoice number, never from the source filename."
+    },
+    {
+      "code": "patch-replaces-extended-fields",
+      "severity": "blocker",
+      "summary": "SCHEMA-CONFIRMED 2026-09-03: `extendedFields` IS updatable via PATCH Update Order, and the call needs ECOM.ORDER_WRITE_ALL_EXTENDED_FIELDS / Manage Orders. MERGE SEMANTICS, re-established 2026-09-05 with a corrected oracle: a partial patch MERGES -- keys the patch omits survive. Three consecutive runs agree. The FIRST version of this probe could not have known: it patched, read once, and judged what survived, so a stale read returning the pre-patch order looked identical to a merge. It now polls until its own included marker is observable before inspecting the omitted keys, and answers UNKNOWN if the patch never becomes visible. What three runs buy and do not buy: they rule out the stale-read artefact and a one-off fluke on this site. They do not establish the behaviour across namespaces, across other extendable objects, or against a future change -- so the MERGE in our writer stays. It costs nothing if the behaviour holds and is the only protection if it ever changes."
+    },
+    {
+      "code": "download-url-default-expiry-is-ten-hours",
+      "severity": "warning",
+      "summary": "SCHEMA-CONFIRMED: Generate File Download Url defaults `expirationInMinutes` to 600. Relying on the default hands out a ten-hour link to a tax document, so the expiry is always passed explicitly and kept small. The member-facing endpoint accepts an ORDER id only and resolves the file id server-side -- accepting a client-supplied file id would let any member fetch another member's invoice."
+    },
+    {
+      "code": "media-import-is-async-and-quota-bounded",
+      "severity": "warning",
+      "summary": "Import File returns `operationStatus: PENDING`; the file is not immediately usable. Poll the descriptor before promising a download, and treat FAILED as a per-document reported outcome. The API also defines a `SITE_QUOTA_EXCEEDED` error, so a large invoice archive can exhaust the site's media quota part-way through -- report per document rather than failing the run."
+    },
+    {
+      "code": "visibility-in-business-manager-is-resolved",
+      "severity": "info",
+      "summary": "RESOLVED 2026-09-05 -- see `business-manager-shows-the-field-but-not-the-document`. This row previously said merchant visibility was unverified and promised neither automatic nor manual visibility. That was never tested and is wrong: the merchant sees these fields on the ORDER DETAIL view, and can toggle them on as COLUMNS in the order list. Kept as a marker so that anyone who met the earlier claim knows it was corrected. What is genuinely absent is the invoice LIST, which is a different surface and does not read order extended fields."
+    },
+    {
+      "code": "string-fields-require-maxlength",
+      "severity": "blocker",
+      "summary": "LIVE-VERIFIED 2026-09-04 on a disposable site: Create Data Extension Schema REJECTS a string field that declares no `maxLength` -- `400 MANDATORY_FIELD_MISSING: <key>.maxLength`. It is a required part of the field definition, not an optional constraint. Both invoice fields therefore declare one (file id 256, invoice number 256); the earlier removal of a length contract went one step too far -- what was unverified was the SPECIFIC 64-character value, not whether a cap is needed at all."
+    },
+    {
+      "code": "order-patch-validates-against-the-schema",
+      "severity": "info",
+      "summary": "LIVE-VERIFIED 2026-09-04: patching a value into an unprovisioned field fails closed with `400 INVALID_PATCH -- verify namespace '_user_fields' exists and the schema contains the specified fields`. So the API independently enforces what the setup-verification guard enforces locally: a value cannot reach a field that was never provisioned. Good news for safety, and it means a provisioning failure surfaces immediately rather than silently dropping data."
+    },
+    {
+      "code": "live-writes-are-intermittently-flaky",
+      "severity": "warning",
+      "summary": "OBSERVED 2026-09-04 across repeated sentinel runs on one disposable site: most runs completed every step, one failed several unrelated steps at once (a schema field not preserved, the Media import not landing, the order values absent) and then succeeded again on the next run with no code change. So these writes are not reliably deterministic, and a single run -- passing OR failing -- is weak evidence. Run a verification more than once before believing it, and never let a downstream conclusion depend on an upstream step having succeeded without checking that it did."
+    },
+    {
+      "code": "business-manager-shows-the-field-but-not-the-document",
+      "severity": "warning",
+      "summary": "OBSERVED 2026-09-05 in Business Manager, on TWO surfaces: (a) the ORDER DETAIL view shows user-defined extended fields when an order is opened; (b) the order LIST offers them in its 'Manage fields' dialog, tagged `User`, to be toggled on as columns. Neither is on by default in the list. So the earlier assumption that nothing renders them is WRONG -- merchant visibility is achievable, manually. What the merchant then sees is the raw value, which for the file id is an opaque Media identifier like `630ce4_....pdf`: visible but not usable, since there is no way to open it from the order list. The number field is genuinely useful there; the file id is not. Closing that gap needs a Wix-side change: a native order-invoice association that renders as something clickable. Still open: whether the column toggle is API-settable, or whether the merchant must enable it by hand."
+    },
+    {
+      "code": "column-labels-use-title-not-x-wix-display",
+      "severity": "warning",
+      "summary": "LIVE-VERIFIED 2026-09-05: a friendly column heading comes from plain JSON Schema `title` (and `description` for the hint). The `x-wix-display` object the Data Extension Schema vocabulary documents -- with `label`, `hint` and `placeholder` -- is REJECTED by the schema service: `400 UNKNOWN_KEYWORD_AT_THIS_LEVEL: <field>.x-wix-display.label`. The docs define a keyword the API does not accept on a user-defined schema, so do not reinstate it from the documentation. Also confirmed in the same probe: `x-wix-permissions` is MANDATORY per field, alongside the already-recorded mandatory `maxLength`."
+    },
+    {
+      "code": "three-fields-three-lifespans",
+      "severity": "info",
+      "summary": "The order carries three invoice fields and they are NOT interchangeable. `Invoice number` is the legal identifier and is permanent. `Invoice file (preserved)` is the document copied into the site's own private Media -- permanent, but opaque: the private file's own URL returns 403 (verified live), so reaching it needs an authorized request. `Invoice link (original)` is where the document has always lived: clickable today, and it rots -- a source-hosted link dies with the source site, a provider-hosted one dies when the merchant leaves that provider. Storing the link was ADDED deliberately on 2026-09-05 after the earlier blanket ban: the merchant already has it on their own store, and these fields are readable by apps and users but not by site visitors, so it widens nothing. It sits beside the preserved copy, never instead of it, and the labels say which is which."
+    },
+    {
+      "code": "the-entity-is-the-producer-not-the-js-constant",
+      "severity": "blocker",
+      "summary": "Setup discovery reads `setupRequirements` from THIS FILE, through domain-knowledge.js. A declaration in JavaScript is not the producer, however canonical it looks. If the JS constant and this file disagree, the requirement the shipped path actually emits is the one declared here, and a seam test that builds its input from the JS helper rather than from here will miss the mismatch. Any change to these fields must land in this file; the JS constant is derived from it, never the other way round."
+    },
+    {
+      "code": "invoice-media-destination",
+      "severity": "medium",
+      "summary": "LIVE-VERIFIED 2026-09-05 on a disposable site: the file id written to the order is an opaque string with nothing to click, so it is not an access path. The path that works is the MEDIA MANAGER -- the import sets `displayName` to `Source invoice <number>`, and the merchant finds and opens the document by searching that name. That makes the import's DESTINATION load-bearing rather than cosmetic: the default `media-root` drops one PDF per order into the same library the merchant keeps their own photos in -- potentially thousands of them. Import File accepts `filePath`, and it CREATES the folder when absent (probe: filePath '/Imported invoices' returned a parentFolderId that was a real folder of that name under media-root, NOT media-root itself). Preserved documents therefore all land in one folder. This does not close that gap: opening an invoice still means leaving the order and searching Media Manager by hand."
+    }
+  ],
+  "mappingGuidance": [
+    "Resolve invoices per run rather than assuming them. Nothing found means nothing is created, and the report says \"no invoices found\", never \"not supported\".",
+    "A number without a document is retained as a reference. Do not render a replacement document.",
+    "Documents on the source filesystem are re-hosted privately without asking, because those bytes die with the source site. Documents on a provider or accounting host are referenced by default and copied only after an explicit merchant opt-in at the approval gate.",
+    "Sampling may discover which key families a store uses, but the selected patterns are then applied across the full in-scope order population, and every discovered document is classified -- not only the sampled ones.",
+    "Read the order before importing: an existing file id suppresses the import, which is what makes a re-run idempotent without depending on the migration crosswalk.",
+    "Set up and verify the two extended fields before any invoice write. A value write is blocked until setup verification passed for that exact field.",
+    "A crosswalk row for the preserved file is an accelerator, not the correctness boundary: re-run safety comes from reading the order's own extended fields first, so a lost crosswalk never causes a second copy of a tax document to be imported."
+  ],
+  "setupRequirements": [
+    {
+      "kind": "extendedFieldSchema",
+      "schemaKind": "data-extension-schema",
+      "targetRef": "ecom/order",
+      "fqdn": "wix.ecom.*.order",
+      "namespace": "_user_fields",
+      "fields": [
+        {
+          "key": "replatformSourceInvoiceNumber",
+          "fieldType": "string",
+          "maxLength": 256,
+          "displayName": "Invoice number",
+          "hint": "Invoice number as issued by the original store. This is the legal identifier and does not change.",
+          "permissionsPreset": "migration-internal",
+          "writePath": "extendedFields.namespaces._user_fields.replatformSourceInvoiceNumber"
+        },
+        {
+          "key": "replatformSourceInvoiceFileId",
+          "fieldType": "string",
+          "maxLength": 256,
+          "displayName": "Invoice file (preserved)",
+          "hint": "The original document, copied into this site's private Media so it survives the old store being switched off. Opening it needs an authorized request; the id alone is not a link.",
+          "permissionsPreset": "migration-internal",
+          "writePath": "extendedFields.namespaces._user_fields.replatformSourceInvoiceFileId"
+        },
+        {
+          "key": "replatformSourceInvoiceUrl",
+          "fieldType": "string",
+          "maxLength": 2048,
+          "displayName": "Invoice link (original)",
+          "hint": "Where the document lives on the original system. Clickable today, but it stops working when the old store is switched off or the payment provider changes — the preserved copy is the durable one.",
+          "permissionsPreset": "migration-internal",
+          "writePath": "extendedFields.namespaces._user_fields.replatformSourceInvoiceUrl"
+        }
+      ]
+    }
+  ],
+  "evidence": [
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/rest/assets/media/media-manager/files/import-file",
+      "note": "Re-checked 2026-09-03. Establishes the `private` boolean, DOCUMENT media type, async PENDING status, the SITE_QUOTA_EXCEEDED error, and that the response echoes `sourceUrl`."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/api-reference/assets/media/media-manager/files/upload-api",
+      "note": "Re-checked 2026-10-22. The document is fetched by the writer (resolved address pinned, redirects re-validated, size capped) and uploaded through Generate File Upload URL (`private`, `filePath`, `fileName`, `mimeType`, `sizeInBytes`) plus a PUT of the bytes with `Content-Type`; the response carries the file descriptor. `files/import` is NOT used because it makes Wix fetch an untrusted source-site URL server-side."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/rest/assets/media/media-manager/files/generate-file-download-url",
+      "note": "Re-checked 2026-09-03. Establishes `expirationInMinutes` defaulting to 600, the ATTACHMENT/INLINE content disposition, and that this is the way to grant access to a private file."
+    },
+    {
+      "type": "wix-docs",
+      "url": "https://dev.wix.com/docs/rest/business-solutions/e-commerce/orders/orders/update-order",
+      "note": "Re-checked 2026-09-03. `extendedFields` is in the updatable-fields list; permissions are ECOM.MODIFY_ORDERS + ECOM.ORDER_WRITE_ALL_EXTENDED_FIELDS; \"to remove a field's value, pass null\", which is why a partial extendedFields drops other namespaces."
+    }
+  ]
+}