51 "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."
52 },
53 {
54 "code": "timestamps-not-backdatable",
55 "severity": "warning",
56 "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."
61 "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]."
62 },
63 {
64 "code": "commingled-source-notes",
65 "severity": "warning",
66 "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."
67 },
68 {
69 "code": "message-cap-5000",
70 "severity": "warning",
71 "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."
72 }
73 ],
74 "mappingGuidance": [
75 "Mapping confirmed by Spec Owner 2026-08-16: 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.",
76 "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.",
77 "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.",
78 "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.",
79 "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."
80 ],
81 "setupRequirements": [
82 "Order crosswalk (source order id -> Wix order id) populated by the order import before any activity write."
88 "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)."
93 "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)."
98 "note": "Sibling entity's mappingGuidance records the same activities follow-up write verified live 2026-08-12 (10/10 order notes) on the probe run; this entity stays verification: docs until a run promotes it directly under its own capability."
103 "note": "commerce.payment-gateway-notes pending-register entry (researched 2026-08-11 with the plugin-rest-child read channel, finding #21); resolved by this entity 2026-08-16."
104 },
105 {
106 "type": "live-run",
107 "path": "migrations/probe-run-20260812/config/wix.env (target site 00000000-0000-0000-0000-000000000000)",
108 "note": "KB verification probe 2026-08-16, safe mode on / site muted: POST /ecom/v1/orders/{orderId}/activities/add with one MERCHANT_COMMENT activity on a freshly imported order → 200; GET on the order read the message back verbatim, including the '[source note — {author}, {ISO date}] …' provenance prefix. Before the call activities[] held only the auto-created ORDER_PLACED entry; after it, the MERCHANT_COMMENT entry carried a server id, createdDate = call time, and authorEmail = the token holder's login email. Probe order d4643149 deleted afterwards."
109 }
110 ],
111 "notes": "Authored 2026-08-16. Mapping confirmed by Spec Owner 2026-08-16. Promoted to verified-live 2026-08-16 by an import-then-add-activity probe under this entity's own capability on the probe site. 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."