> 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/how-the-cegid-retail-y2-connector-works.md).

# How the Cegid Retail Y2 connector works

Understand how the Cegid Retail Y2 connector exchanges customer, loyalty, voucher, and sales data with The Wallet Crew.

Two principles explain the connector's behaviour: Cegid remains the system of record, and the connector reads data on demand.

### Cegid holds the data, The Wallet Crew holds the pass

The connector does not act as a separate Cegid customer database. When an enrolment form is submitted, the profile is written to Cegid Retail Y2 and then read back. When a pass is rendered, its customer, loyalty, and voucher data is retrieved from Cegid. The Wallet Crew retains the pass and identifiers needed to link it to the related Cegid record.

{% hint style="warning" %}
If a customer record is overwritten or corrupted in Cegid, The Wallet Crew cannot restore it. There is no second copy. Recovery is a Cegid matter, through Cegid's own audit trail.
{% endhint %}

### The two directions of traffic

Data moves between the two systems in two quite different ways, and confusing them is a common source of misunderstanding.

```mermaid
flowchart LR
  subgraph twc["The Wallet Crew"]
    Form["Enrolment flow"]
    Build["Pass build"]
    Notif["Business notification endpoint"]
  end
  Y2["Cegid Retail Y2<br/>system of record"]

  Form -->|"Write the profile, then read it back"| Y2
  Build -->|"Read customer, loyalty and vouchers on every build"| Y2
  Y2 -.->|"Optional notification, identifiers only"| Notif
  Notif -->|"Read the affected record, refresh the passes"| Y2
```

**Outbound calls** carry almost all of the traffic. The connector calls the Y2 web services to search for a customer, create or update a profile, create a loyalty card, list vouchers, or fetch a sales document. These calls happen when a form is submitted and again whenever a pass is built. Because Apple Wallet and Google Wallet poll for pass updates on their own schedule, a single customer can generate many reads over a day, which is why caching and rate limiting exist. Both are covered in [Advanced configuration](/connectors/pos/cegid/setup-and-configuration/advanced-configuration.md).

**Inbound business notifications** are optional and carry very little data. Cegid can be configured to notify The Wallet Crew when a customer is created or updated, a receipt is created, or a loyalty card operation occurs. The notification carries identifiers, not content: the connector reacts by reading the affected record back from Cegid and refreshing the relevant passes.

{% hint style="info" %}
Because notifications trigger reads rather than replacing them, enabling business notifications increases Cegid traffic rather than reducing it. The benefit is freshness, not efficiency.
{% endhint %}

### What ends up on a pass

When the connector resolves a customer, it writes a small set of identifiers onto the pass so that later reads can go straight to the right Cegid record instead of searching again. The Cegid customer identifier is stored as `id.y2.customerId`, and a linked loyalty card as `y2.loyaltyCardId`. Gift cards, certificates, and deposits each get their own identifier in the same family.

Loyalty values are exposed for use in pass templates under a `loyalty.` prefix: the programme name, activation and expiration dates, the point balance, and for stored-value products an amount and currency.

{% hint style="warning" %}
The connector also places the raw Cegid response on the account under keys beginning `debug.y2.`. These are **not** pass template fields. They exist in the data handed to a mapping script, as an aid to writing and debugging mappings, and are described in [Customise the mapping](/connectors/pos/cegid/customer-data-and-loyalty/customise-the-mapping.md).
{% endhint %}

### The moving parts

Three kinds of component make up the connector, and tenant configuration refers to them by name.

**Customer providers** read from Cegid when a pass or form needs data. The `y2` provider fetches the customer profile, `y2.loyalty` fetches loyalty cards, `y2.customerCashOperations` and `y2.cashOperations` fetch vouchers and stored value, and `y2.tickets` fetches sales documents.

**Flow elements** are the steps in an enrolment or update flow that write to Cegid. The `y2Customer` step creates or updates the profile, `y2Loyalty` creates a loyalty card, `y2PendingTicket` raises a held receipt, and `y2ExecuteScheduledTask` triggers a Cegid scheduled task.

**Scheduled work** runs on its own timetable. The `cegid.newOrderWalletUpdate` task refreshes passes affected by recent orders, looking back one hour by default.

### FAQ

<details>

<summary><strong>Does The Wallet Crew store customer personal data from Cegid?</strong></summary>

The connector reads customer data from Cegid when needed to build or update a pass. It does not maintain a separate Cegid customer database.

</details>

<details>

<summary><strong>Why does a single customer generate so many Cegid calls?</strong></summary>

Apple Wallet and Google Wallet poll for pass updates independently of any user action, and each poll that results in a pass being rebuilt reads from Cegid. Caching, described in [Advanced configuration](/connectors/pos/cegid/setup-and-configuration/advanced-configuration.md), is the intended remedy.

</details>

<details>

<summary><strong>Are business notifications required?</strong></summary>

No. Without them, wallet data still refreshes whenever a pass is rebuilt. Notifications make that refresh happen promptly after activity in store rather than on the wallet's own schedule.

</details>


---

# 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/how-the-cegid-retail-y2-connector-works.md?ask=<question>&goal=<user_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.