27 "decision": "Contacts V5 is GA (docs verified 2026-08-04; FR-014 resolved). 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)."
28 },
29 "alternateWrites": [
30 {
31 "surface": "Contacts V5",
32 "endpoint": "POST /contacts/v5/contacts",
33 "writerId": "createContact",
34 "verification": "unverified",
35 "importSafe": true,
36 "bulk": false,
37 "when": "Single-record creates outside the bulk import path; same flat GA contact shape."
38 },
39 {
40 "surface": "Contacts V4",
41 "endpoint": "POST /contacts/v4/contacts",
42 "writerId": null,
43 "verification": "verified-live",
44 "importSafe": true,
45 "bulk": false,
46 "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."
53 "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",
57 "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.",
58 "setupGuidance": [
59 "Define contact custom fields during setup (Data Extension Schema, FQDN wix.contacts.*.contact) before writing contact values; verify live given the docs inconsistency.",
60 "Persist the returned field key from setup; do not invent the final key from the display name.",
61 "Write contact extended field values under extendedFields.namespaces._user_fields[returnedKey] with V5 writers; info.extendedFields is the V4 surface only.",
62 "Use Contacts V5 for contact record writes by default; surface current verification level in execution reports."
101 { "code": "created-date-server-controlled", "severity": "warning", "summary": "Original contact created dates are not writable as native createdDate." },
102 { "code": "consent-sensitive", "severity": "blocker", "summary": "Only import subscription status with proof of consent." }
103 ],
104 "mappingGuidance": [
105 "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.",
106 "Prefer contact extended fields for source CRM metadata before CMS fallback.",
107 "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.",
108 "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.",
109 "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."
110 ],
111 "setupRequirements": [
112 "Contact extended fields when source-only CRM fields are preserved natively.",
113 "Data Extension Schema setup (FQDN wix.contacts.*.contact) before contact writers emit extendedFields values; verify live given the DES supported-objects docs inconsistency.",
114 "V5 writers remain UNVERIFIED in execution reports until a live contract test with Contacts permissions promotes create/query/update."