59 "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."
60 },
61 {
62 "code": "timestamps-not-backdatable",
63 "severity": "warning",
64 "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."
69 "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]."
70 },
71 {
72 "code": "commingled-source-notes",
73 "severity": "warning",
74 "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."
75 },
76 {
77 "code": "message-cap-5000",
78 "severity": "warning",
79 "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."
80 },
81 {
82 "code": "add-activities-not-idempotent",
83 "severity": "warning",
84 "summary": "Add Activities has no client-assigned id and no upsert: a resend after an unknown outcome adds the comments again. Before resending a `started`/`succeeded_unverified` note, read the order back (`getOrder`) and match MERCHANT_COMMENT messages by exact text."
85 }
86 ],
87 "mappingGuidance": [
88 "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.",
89 "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.",
90 "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.",
91 "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.",
92 "Write with rp-target-wix `addOrderMerchantNotes({ orderId, messages })` (builder `buildAddOrderMerchantNotesRequest`): one order per call, 1-300 messages, each 1-5000 chars. Resolve `orderId` through the readiness gate (`resolveReference('ecom/order', orderSourceKey, 'orderId')`) — the edge is per-record, so a note on a held or not-yet-imported order is deferred while the rest are written. Never call this endpoint with sendDirectRest: the import client refuses unmarked writes."
93 ],
94 "setupRequirements": [
95 "Order crosswalk (source order id -> Wix order id) populated by the order import before any activity write."
101 "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)."
106 "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)."
111 "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."
116 "note": "The plugin-rest-child read channel supplies commerce.payment-gateway-notes, which this entity resolves."
117 },
118 {
119 "type": "live-run",
120 "path": "anonymized-live-verification",
121 "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."
122 }
123 ],
124 "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. Writer `addOrderMerchantNotes` added 2026-10-25: the earlier direct-REST plan was refused by the import client, which accepts only marked writes."