> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/connectors/pos/cegid/customer-data-and-loyalty/cegid-retail-y2-fields-mapping.md).
# Cegid Retail Y2 fields mapping
The customer create and update lifecycle, and the default field mapping between The Wallet Crew and Cegid Retail Y2, including its conditions.
The connector creates and updates customer records in Cegid Retail Y2 from enrolment forms, and reads them back to populate passes and pre-fill forms. This page documents that lifecycle and the field mapping applied by default.
### The create and update lifecycle
When an enrolment form is submitted, the connector maps the submitted data onto the Cegid customer structure, applies the brand's own mapping script if one is deployed, and writes the record. It then **reads the record back from Cegid** rather than assuming the write took effect as sent, which is why values normalised or rejected by Cegid are reflected immediately rather than at the next read.
### Finding an existing customer
Where a pass already carries a Cegid customer identifier, that identifier is used directly. Where it does not, the connector searches Cegid to avoid creating a duplicate.
That search runs in parallel across the email address and, for the telephone number, several formats — as entered, with the international prefix in either notation, and in national form — each checked against the four telephone fields a Cegid record carries. Closed records are excluded.
{% hint style="warning" %}
If more than one record matches, the most recently modified is used and the ambiguity is recorded in the logs. This is not rare: shared household telephone numbers and staff test records both produce it. Where duplicate matches are frequent, the underlying duplicates should be resolved in Cegid rather than tolerated, because which record a customer lands on can otherwise change over time.
{% endhint %}
### Default field mapping
The mapping below is applied before any mapping script runs. Almost every field is conditional, and the conditions are the source of most reported surprises: a field that appears not to map is usually a field whose condition was not met.
| Wallet Crew field | Cegid field | Conditions and transformation |
| --------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email` | `EmailData.Email` | Always written. |
| `phoneNumber` | `PhoneData.CellularPhoneNumber` | Written when present. |
| `firstName` | `FirstName` | Always written. |
| `lastName` | `LastName` | Mandatory in Cegid. If blank on update, re-fetched from Cegid; if still blank, set to the literal `NEOSTORE`. On read, a last name of `NEOSTORE` is suppressed. |
| `sex` | `Sex` | Only `M` or `F` are accepted. Any other value is written as empty. |
| `title` | `TitleId` | Written when present. |
| `advisor`, else `advisorId` | `SalesPersonId` | The first of the two that is present. |
| `storeId` | `UsualStoreId` | Written when present. On read, falls back to the store of creation when the store of attachment is empty. |
| `isProspect` | `IsProspect` | Always written, defaulting to false. |
| `birthDate` | `BirthDateData` | Day and month accepted when greater than zero; year only when after 1900 and not in the future. If all three are present but do not form a valid past date, the whole birth date is cleared. |
| `address` | `AddressData.AddressLine1` | Always written. |
| `streetNumber` | `AddressData.AddressLine2` | Always written. |
| `postCode`, else `zipCode` | `AddressData.ZipCode` | The first of the two that is present. Read back into `postCode`. |
| `city` | `AddressData.City` | Always written. |
| `country` | `AddressData.CountryId` | **Only written when the value is exactly two characters**, and then as an ISO-2 code. Anything else is discarded with a warning. On read, Cegid's own identifier is converted back to ISO-2. |
| `nationality` | `NationalityId` | Written when present. |
| `consents_email` | `OptinEmail` and `EmailData.EmailingAccepted` | Written **only when an email address is present**. True becomes brand-only consent, false becomes do-not-use. |
| `consents_sms` | `OptinMobile` | Written **only when a mobile number is present**. |
| `consents_post` | `OptinPostal` | Written **only when an address line, city, or postcode is present**. |
| `consents_emailReceipt` | `EmailData.SendReceiptByMail` | Written only when an email address is present. |
| `lastUpdated` | `LastModificationDate` | Read only. |
{% hint style="danger" %}
The consent conditions are the most misread part of this table. A consent is written only when the channel it governs has data, so a form that collects postal consent but no address records nothing in Cegid, and the absence is silent. Where consents appear not to save, the first thing to check is whether the corresponding contact detail was captured on the same form.
{% endhint %}
### Reading back into a form
The same mapping applies in reverse when a customer is loaded, to pre-fill an edit form or to populate a pass. Empty Cegid values are not written over existing wallet values, and two sentinel values are filtered: a last name of `NEOSTORE`, and a birth year of 1900 or zero, which Cegid uses to mean unset.
### Extending the mapping
The default mapping covers standard identity and contact fields. Everything else a brand records in Cegid — marketing preferences in free fields, language, fiscal identifiers, wallet installation state — is set through a mapping script, which runs after the default mapping and can override any of it. In practice almost every brand running this connector deploys one; see [Customise the mapping](/connectors/pos/cegid/customer-data-and-loyalty/customise-the-mapping.md).
The structure of the Cegid customer object a script works with is documented in the [Scripting reference](/connectors/pos/cegid/developer-reference/scripting-reference.md).
Use this structure to find the exact Cegid property to read or write in a custom mapping script.
### FAQ
Why is a customer's country missing in Cegid?
The country value was not exactly two characters. The connector writes ISO-2 codes only, and discards anything else rather than sending a value Cegid would reject.
Why does a customer have the last name NEOSTORE?
Cegid requires a last name. Where a form allows it to be empty and no existing value can be recovered, that placeholder is written so the record can be created at all. It is hidden when read back, but visible in Cegid. Making the field mandatory on the form avoids it.
Are consents overwritten on every update?
Only where the corresponding contact detail is present on the submission. A brand that manages consent primarily in Cegid should confirm which fields the enrolment form submits, since a form that carries a consent value will write it.
Can additional fields be synchronised?
Yes. Any field on the Cegid customer record can be mapped with a script, including the free texts and free tables a brand defines for itself. See [Customise the mapping](/connectors/pos/cegid/customer-data-and-loyalty/customise-the-mapping.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.thewalletcrew.io/connectors/pos/cegid/customer-data-and-loyalty/cegid-retail-y2-fields-mapping.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
