# Livestore

This guide explains how to enable the **external customer form** extension in **Cegid Retail Live Store**.

Once enabled, LiveStore opens an enrolment form hosted by The Wallet Crew when staff create or edit a customer. After submission, staff are redirected back to the LiveStore customer details page. You can also enable a QR code mode so customers can complete enrolment on their own phone.

<details>

<summary><strong>Real-world examples</strong></summary>

* A sales associate creates a new loyalty customer in Live Store. The Wallet Crew form collects the data and creates the customer in Cegid Y2.
* A sales associate edits an existing customer. The Wallet Crew form updates the customer in Cegid Y2, then returns to the customer detail page.
* A store uses a tablet at the entrance. A customer scans a QR code and completes enrolment in a self-service flow.

</details>

### Prerequisites

You need access to configure both Live Store and The Wallet Crew.

On the Cegid side, you need permission to edit **newpossettings** at the **global**, **country**, or **store** level.

On The Wallet Crew side, your tenant must have the **Cegid Retail Y2 connector** configured and working.

* If you have not connected Y2 yet, start with [Connect with Cegid Retail Y2](https://docs.thewalletcrew.io/connect/pos/cegid/connect-with-cegid-retail-y2).
* If you need to verify which customer fields are synced, see [Cegid Retail Y2 fields mapping](https://docs.thewalletcrew.io/connect/pos/cegid/cegid-retail-y2-fields-mapping).

### Setup

{% stepper %}
{% step %}

#### Create an API key in The Wallet Crew

Create an API key that Live Store will use to call The Wallet Crew endpoints.

1. Open API Key management page

<p align="center"><a href="https://admin.thewalletcrew.io/tenant/~/apiKeys" class="button secondary" data-icon="chevrons-right">API Key management</a><br></p>

2. Create a new API key with scope `tenant.y2.listener`.
3. Copy the generated value and store it in your secret manager.

You will use it as the `X-API-KEY` header in LiveStore configuration.
{% endstep %}

{% step %}

#### Configure The Wallet Crew (runtime)

This extension requires a LiveStore specific configuration in your tenant runtime.

Update your runtime configuration:

1. In Advanced Configuration, on file `security.yml`, add an account challenger of type `livestore`.
2. Update your enrolment flow to add a `livestore` flow element.
3. Create `server/livestore.yml`:

```yaml
layout: mobile_ls
useTabletMode: false
provider: y2
customerRedirectLayout: mobile_livestore
```

4. Create or update both referenced layouts (`mobile_ls` and `mobile_livestore`).
   {% endstep %}

{% step %}

#### Configure Live Store (newpossettings)

Open the newpossettings admin in your Live Store environment:

* Test: `https://<your-tenant>-test-retail-ondemand.cegid.cloud/Y2/newpossettings/`
* Prod: `https://<your-tenant>-retail-ondemand.cegid.cloud/Y2/newpossettings/`

Configure the extension at the **global**, **country**, or **store** level. It is not available at the register level.

<div data-with-frame="true"><figure><img src="https://3566051324-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWLc8AHXW4tdrAXUBfrYF%2Fuploads%2Fgit-blob-9f0ec5a2400496e78d2ed2ae1ea7a63e1d42ad0b%2Flivestore_1.png?alt=media" alt="Cegid newpossettings scope selection showing Global, Country, and Store level configuration."><figcaption><p>Choose the scope where the extension applies (global, country, or store).</p></figcaption></figure></div>

Set the `LiveStore_Connector_ExternalCustomerForm` entry with your tenant values:

{% tabs %}
{% tab title="Production" %}

```yaml
apiEndpoint: https://app.neostore.cloud/api/<YOUR_TENANTID>/external/livestore/session
endpoint: https://app.neostore.cloud/api/<YOUR_TENANTID>/external/livestore
headerName: X-API-KEY
headerValue: <YOUR_API_KEY>
```

{% hint style="info" %}
Don't forget to replace \<YOUR\_TENANTID> and \<YOUR\_API\_KEY> with the associated value
{% endhint %}

{% hint style="info" %}
If you do have a custom domain configure, replace app.neostore.cloud with your custom domain
{% endhint %}
{% endtab %}

{% tab title="Staging" %}

```yaml
active: true
apiEndpoint: https://app-qa.neostore.cloud/api/<YOUR_TENANTID>/external/livestore/session
endpoint: https://app-qa.neostore.cloud/api/<YOUR_TENANTID>/external/livestore
headerName: X-API-KEY
headerValue: <YOUR_API_KEY>
```

{% hint style="info" %}
Don't forget to replace \<YOUR\_TENANTID> and \<YOUR\_API\_KEY> with the associated value
{% endhint %}
{% endtab %}
{% endtabs %}

If you need to pin a specific store, set the extension at the store level and add `storeId`:

```yaml
endpoint: https://app.neostore.cloud/api/<tenantId>/external/livestore?storeId=<storeId>
```

{% endstep %}

{% step %}

#### Validate the flow

Validate in a test environment first.

1. In Live Store, open the customer create or edit screen.
2. Confirm Live Store redirects to the enrolment form.
3. Submit the form with test data.
4. Confirm you are redirected back to the Live Store customer details page.

If you get an authorization error, double-check the `X-API-KEY` header value and the API key scope.
{% endstep %}
{% endstepper %}

### Optional: show a QR code for self-service enrolment

Use this when a store uses a tablet and wants customers to continue on their own phone.

Enable tablet mode in `server/livestore.yml` and point the redirect layout to a mobile-friendly layout:

```yaml
layout: pos
useTabletMode: true
provider: y2
customerRedirectLayout: mobile
```

### FAQ

<details>

<summary><strong>Where do I configure the extension in Live Store?</strong></summary>

Use **newpossettings**. Configure it at the **global**, **country**, or **store** level. Live Store does not support this extension at the register level.

</details>

<details>

<summary><strong>Which URL should I use for <code>endpoint</code> and <code>apiEndpoint</code>?</strong></summary>

Use the `https://app.neostore.cloud/api/<tenantId>/external/livestore` base and replace `<tenantId>` with your tenant ID in The Wallet Crew.

If your project uses a different environment (staging, QA, or a custom domain), use the base URL provided by The Wallet Crew during setup.

</details>

<details>

<summary><strong>Can I reuse the same API key for test and production?</strong></summary>

Avoid it. Use separate API keys per environment. Rotate keys if you suspect they were exposed.

</details>

<details>

<summary><strong>Live Store redirects, but I end up on an error page. What should I check?</strong></summary>

Start with the basics. Confirm the `endpoint` URL is reachable from the Live Store network. Confirm the `X-API-KEY` header is present and correct. Then confirm the Cegid Retail Y2 connector is enabled in The Wallet Crew and can reach your Y2 services.

</details>