58 "decision": "Contacts V5 is GA (docs verified 2026-08-04). The GA contact shape is flat: main email/phone + additionalEmails/additionalPhones, addresses[] with postal fields nested under `address`, company as { name, jobTitle }; no `info` wrapper. Bulk upsert (100/call, synchronous, per-item results, externalId set-once) is the import path; createContact/updateContact cover single-record needs. Live create/query/update verification is still pending a token with Contacts permissions (2026-07-26 probe got 403)."
59 },
60 "alternateWrites": [
61 {
62 "surface": "Contacts V5",
63 "endpoint": "POST /contacts/v5/contacts",
64 "writerId": "createContact",
65 "verification": "unverified",
66 "importSafe": true,
67 "bulk": false,
68 "when": "Single-record creates outside the bulk import path; same flat GA contact shape."
69 },
70 {
71 "surface": "Contacts V4",
72 "endpoint": "POST /contacts/v4/contacts",
73 "writerId": null,
74 "verification": "verified-live",
75 "importSafe": true,
76 "bulk": false,
77 "when": "Legacy compatibility fallback only when a migration explicitly requires the V4 surface (e.g. V4 labels or V4 info.extendedFields semantics); requires an explicit legacy writer or direct REST plan because createContact targets V5."
84 "definitionOperation": "Create Data Extension Schema (FQDN wix.contacts.*.contact) — resolve the concrete endpoint from the Data Extension Schema API docs during setup; not recorded here to avoid guessing",
88 "contactsV5Status": "At GA (verified 2026-08-04) the V5 contact-object docs route custom field definitions through the Data Extension Schema API with FQDN wix.contacts.*.contact, and the V5 contact carries values under extendedFields.namespaces.<ns>. CAVEAT: the Data Extension Schema intro's supported-objects table does not list contacts yet (docs inconsistency at GA cutover) — verify the DES path live during setup before relying on it. The V4 Contacts Extended Fields API (POST /contacts/v4/extended-fields, values under info.extendedFields) still exists but pairs with the V4 write surface only; do not mix the two.",
89 "setupGuidance": [
90 "Define contact custom fields during setup (Data Extension Schema, FQDN wix.contacts.*.contact) before writing contact values; verify live given the docs inconsistency.",
91 "Persist the returned field key from setup; do not invent the final key from the display name.",
92 "Write contact extended field values under extendedFields.namespaces._user_fields[returnedKey] with V5 writers; info.extendedFields is the V4 surface only.",
93 "Use Contacts V5 for contact record writes by default; surface current verification level in execution reports."
130 "when": "Use for source CRM fields that should not or cannot live in contact extended fields."
131 }
132 ],
133 "reliability": {
134 "status": "partially-reliable",
135 "flags": []
136 },
137 "pitfalls": [
138 {
139 "code": "created-date-server-controlled",
140 "severity": "warning",
141 "summary": "Original contact created dates are not writable as native createdDate."
142 },
143 {
144 "code": "consent-sensitive",
145 "severity": "blocker",
146 "summary": "Only import subscription status with proof of consent."
147 }
148 ],
149 "mappingGuidance": [
150 "WooCommerce guest-checkout buyers are not WP users and never appear in /wc/v3/customers (guest orders carry customer_id: 0) — also derive contacts from order billing/shipping details on /wc/v3/orders, deduped by email via Bulk Upsert, so every imported order can carry a crosswalked buyerInfo.contactId.",
151 "Prefer contact extended fields for source CRM metadata before CMS fallback.",
152 "Use Contacts V5 (GA) as the default contact writer surface; the GA contact shape is flat (main email/phone + additionalEmails/additionalPhones, addresses[] with nested address, company object) — never emit the V4 info wrapper to V5 endpoints.",
153 "For contact custom fields, setup must define the Data Extension Schema (FQDN wix.contacts.*.contact) and carry the returned key into contact writers under extendedFields.namespaces._user_fields.",
154 "Source labels map to V5 tags (tags.privateTags.tagIds via the Tags API, FQDN wix.contacts.*.contact); resolve the tag/label story during setup before planning post-import label-wave automations."
155 ],
156 "setupRequirements": [
157 "Contact extended fields when source-only CRM fields are preserved natively.",
158 "Data Extension Schema setup (FQDN wix.contacts.*.contact) before contact writers emit extendedFields values; verify live given the DES supported-objects docs inconsistency.",
159 "V5 writers remain UNVERIFIED in execution reports until a live contract test with Contacts permissions promotes create/query/update."