25 "decision": "Import Order is the dedicated migration path (ECOM-01): settable purchasedDate/createdDate/number, values stored as-is, no side effects (no buyer notifications, no inventory adjustment, no contact/invoice/receipt/subscription creation; only the OrderImported event fires). Beta, single-order only (no bulk endpoint), no SHOPIFY/WOOCOMMERCE channel enums (use OTHER_PLATFORM), analytics inclusion not suppressible. Rollback via Bulk Delete Imported Orders; re-send with the same id fully replaces."
26 },
27 "alternateWrites": [
28 {
29 "surface": "eCom Orders",
30 "endpoint": "POST /ecom/v1/orders",
31 "writerId": "createOrder",
32 "verification": "unverified",
33 "importSafe": false,
34 "bulk": false,
35 "when": "Live-commerce order creation only — NEVER for historical import: decrements inventory, sends buyer confirmation email, auto-creates a contact (ECOM-02)."
36 }
37 ],
38 "safeModeContactFields": [
39 {
40 "kind": "email",
41 "targetPath": "billingInfo.email",
42 "source": "target-schema",
43 "notes": "Historical order billing email on the order object; codegen must resolve request wrappers."
44 },
45 {
46 "kind": "phone",
47 "targetPath": "billingInfo.phone",
48 "source": "target-schema",
49 "notes": "Historical order billing phone on the order object; codegen must resolve request wrappers."
50 },
51 {
52 "kind": "email",
53 "targetPath": "shippingInfo.email",
54 "source": "target-schema",
55 "notes": "Historical order shipping email on the order object when present."
56 },
57 {
58 "kind": "phone",
59 "targetPath": "shippingInfo.phone",
60 "source": "target-schema",
61 "notes": "Historical order shipping phone on the order object when present."
62 },
63 {
64 "kind": "email",
65 "targetPath": "buyerInfo.email",
66 "source": "target-schema",
67 "notes": "Historical order buyer email on the order object when present."
68 },
69 {
70 "kind": "phone",
71 "targetPath": "buyerInfo.phone",
72 "source": "target-schema",
73 "notes": "Historical order buyer phone on the order object when present."
74 }
75 ],
76 "fallbacks": [
77 { "classification": "cms", "when": "Use for separate audit/history records or unsupported nested source details." }
81 { "code": "create-order-not-import-safe", "severity": "blocker", "summary": "Never route historical orders through createOrder — it decrements inventory, emails the buyer, and auto-creates contacts; importOrder is the only import-safe writer." },
82 { "code": "contact-crosswalk-sequencing", "severity": "blocker", "summary": "Import creates no contact; contacts (including guest buyers from order billing emails) must be imported first so buyerInfo.contactId can be passed." },
83 { "code": "beta-single-order", "severity": "warning", "summary": "Import Order is Beta and single-order only (no bulk endpoint); undocumented rate limits apply at scale." },
84 { "code": "analytics-not-suppressible", "severity": "warning", "summary": "Imported orders appear in sales analytics/reports with no documented exclusion flag." },
85 { "code": "imported-orders-invisible-to-events", "severity": "warning", "summary": "Only the OrderImported event fires and only eCom's own indexer consumes it — imported orders never materialize in contacts/loyalty/event-driven views." }
86 ],
87 "mappingGuidance": [
88 "Resolve product, variation, contact, and coupon crosswalks before writing orders.",
89 "Contacts import first, orders second: Import Order accepts buyerInfo.contactId (schema-checked 2026-08-04) but creates no contact itself — always pass the crosswalked contact ID, including for guest buyers derived from order billing emails (see crm/contact). The field doc's 'automatically created if one doesn't exist' text is shared with live Create Order and is unverified for the import path — do not rely on it.",
90 "Use order and line-item extended fields for source-only metadata when configured."
91 ],
92 "setupRequirements": ["Order data extension schema if extended fields are used.", "Side-effect verification before execution."],