Wikiadmin: Created page with "(mostly answered by Claude.AI) At the UI level, there is '''no direct Email ID field on the Customer DocType itself'''. It '''is''' redundant by design, and it's a known architectural quirk in ERPNext. Here's why both exist and what each one actually does: ---- == The Two Fields Explained == === 1. `Contact.is_primary_contact` (on the Contact DocType) === * This is a '''flag on the Contact record itself''' * It means: ''"among all contacts linked to this..."

2026-05-22T06:25:45Z

Created page with "(mostly answered by Claude.AI) At the UI level, there is '''no direct Email ID field on the Customer DocType itself'''. It '''is''' redundant by design, and it's a known architectural quirk in ERPNext. Here's why both exist and what each one actually does: ---- == The Two Fields Explained == === 1. <code>Contact.is_primary_contact</code> (on the Contact DocType) === * This is a '''flag on the Contact record itself''' * It means: ''"among all contacts linked to this..."

New page

(mostly answered by Claude.AI)

At the UI level, there is '''no direct Email ID field on the Customer DocType itself'''.

It '''is''' redundant by design, and it's a known architectural quirk in ERPNext. Here's why both exist and what each one actually does:
----

== The Two Fields Explained ==

=== 1. <code>Contact.is_primary_contact</code> (on the Contact DocType) ===

* This is a '''flag on the Contact record itself'''
* It means: ''"among all contacts linked to this customer, this one is the primary"''
* It is set when you tick '''"Is Primary Contact"''' on the Contact form
* ERPNext uses this to '''auto-populate''' contact fields in transactions (Sales Order, Sales Invoice, etc.)
* '''Problem:''' Nothing enforces uniqueness — two contacts for the same customer can both have <code>is_primary_contact = 1</code>, which is a data integrity gap

----

=== 2. <code>Customer.customer_primary_contact</code> (on the Customer DocType) ===

* This is a '''direct link field''' (a <code>Link</code> field pointing to <code>Contact</code>) stored on the Customer record itself
* It gives you a '''single, authoritative lookup''': ''"what is the primary contact for this customer?"'' without having to query the Contact table at all
* It is updated automatically by ERPNext when a contact is marked as primary
* Much faster for API queries — one GET on the Customer record returns the primary contact name immediately

----

== Why Both Exist — The Real Reason ==
<code>Customer ──────────────────────────────────────────────────────────┐
customer_primary_contact = "Jane Smith" ← fast denormalised │
lookup │
│
Contact (Jane Smith) │
links → [{ link_doctype: "Customer", link_name: "CUST-00001" }] │
is_primary_contact = 1 ← flag used during transaction │
auto-population & filtering ───────────┘</code>
It is essentially '''denormalisation for performance''' — a classic database trade-off:
{| class="wikitable"
!Concern
!<code>is_primary_contact</code>
!<code>customer_primary_contact</code>
|-
|'''Where stored'''
|Contact record
|Customer record
|-
|'''Purpose'''
|Flag for filtering/transactions
|Fast direct lookup
|-
|'''Query cost'''
|Requires JOIN / filter on Contact
|Single field on Customer fetch
|-
|'''Risk'''
|Multiple contacts can be flagged <code>1</code>
|Can go stale if not synced
|-
|'''Updated by'''
|User manually / Contact save hook
|ERPNext hook on Contact save
|}
----

== The Sync Risk ==
The real danger is they can '''fall out of sync''':

* If you update <code>is_primary_contact</code> via a direct API PATCH on the Contact but ERPNext's server-side hook doesn't fire correctly, <code>customer_primary_contact</code> on the Customer won't update
* If you delete a Contact that is the primary, <code>customer_primary_contact</code> may hold a '''dead reference''' until another contact is promoted

----

== Practical Advice ==
{| class="wikitable"
!Use case
!Use this field
|-
|Fetch primary contact quickly in one API call
|<code>Customer.customer_primary_contact</code>
|-
|Filter all contacts to find which is primary
|<code>Contact.is_primary_contact = 1</code>
|-
|Trust for data integrity
|Neither alone — '''verify both match'''
|-
|Setting a new primary contact
|Always do it via the '''ERPNext UI or server-side method''' so both fields stay in sync
|}
---- It's a deliberate denormalisation that trades data integrity risk for query performance, and it's something ERPNext developers themselves have debated in the Frappe GitHub issues over the years.

ERPNext's <code>Address</code> DocType also has its own <code>email_id</code> field, completely separate from the Contact email chain.
----

== The Full Picture ==
<code>Customer (CUST-00001 - "Acme Corp")
│
├──► customer_primary_contact ──► Contact "Jane Smith"
│ │ └── email_ids[]
│ │ └── jane@acme.com ← person email
│
├──► customer_primary_address ──► Address "Acme Corp-Billing"
│ └── email_id: accounts@acme.com ← address email
│
└──► Dynamic Links (multiple)
│
├── Address "Acme Corp-Billing"
│ └── email_id: accounts@acme.com
│
├── Address "Acme Corp-Shipping"
│ └── email_id: warehouse@acme.com
│
└── Address "Acme Corp-Head Office"
└── email_id: info@acme.com</code>
----

== Three Completely Separate Email Pools ==
{| class="wikitable"
!Source
!Field
!Typical Use
!Example
|-
|<code>Contact.email_ids[]</code>
|<code>email_id</code>
|Person-to-person communication
|<code>jane@acme.com</code>
|-
|<code>Address.email_id</code>
|<code>email_id</code>
|Location/department email
|<code>accounts@acme.com</code>
|-
|<code>Customer</code>
|''(none)''
|—
|—
|}
Each pool is '''entirely independent''' — no sync, no relationship between them whatsoever.
----

== Why Address Has Its Own Email ==
The <code>Address</code> DocType is designed to represent a '''physical or operational location''', and in B2B that location often has its own functional email:
<code>Acme Corp - Billing Address → accounts@acme.com (AP/AR team)
Acme Corp - Shipping Address → warehouse@acme.com (logistics team)
Acme Corp - Head Office → info@acme.com (general enquiries)</code>
This makes sense in the real world — when you send an '''invoice''', you email the billing address email, not Jane's personal email.
----

== How ERPNext Decides Which Email to Use ==
This is where it gets messy. Depending on the transaction type, ERPNext picks email from '''different sources''':
{| class="wikitable"
!Transaction
!Where ERPNext looks for email
|-
|Sales Invoice (send via email)
|<code>customer_primary_contact → email_id</code>
|-
|Print & Email from Address
|<code>Address.email_id</code>
|-
|Dunning / Payment Reminder
|<code>customer_primary_contact → email_id</code>
|-
|Shipping Notification
|<code>Address.email_id</code> (shipping address)
|-
|Portal / User login
|<code>Contact.email_ids[]</code>
|}
There is '''no single unified "customer email"''' — it depends entirely on the context and which button you press.
----

----

== Summary of the Design Problem ==
{| class="wikitable"
!Issue
!Impact
|-
|No single <code>Customer.email</code> field
|Must chase 2+ DocTypes to find any email
|-
|Address email ≠ Contact email
|Easy to send invoices to the wrong place
|-
|No enforced "use this email for invoices" rule
|Relies on user discipline
|-
|Multiple addresses, each with own email
|No clear hierarchy without <code>is_primary_address</code> logic
|-
|ERPNext picks email source based on transaction
|Inconsistent and surprising behaviour
|}
It is a '''flexible but fragile''' design — powerful when set up correctly, but very easy to end up with missing or stale email data across the system.

So many Email addresses - Revision history