> 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/e-commerce.md).

# E-commerce

Add wallet buttons to e-commerce journeys to distribute account-linked Apple Wallet and Google Wallet passes, then use them in store with POS scanning.

E-commerce integration is typically an **omnichannel** topic. The goal is to let customers use the same account online and in-store, without requiring a mobile app. A wallet pass acts as a persistent, scannable credential that links the e-commerce identity to in-store systems through POS integration.

This approach reduces dependency on checkout emails and account logins at the point of sale. It also simplifies customer recognition, loyalty attribution, and benefit redemption across channels.

<details>

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

* Retail loyalty: a loyalty pass is added from the e-commerce account page, then scanned in-store to attach purchases to the profile.
* Clienteling: a membership pass barcode is scanned to retrieve tier and benefits in POS or clienteling tools.
* Gift cards: a wallet gift card is added from the account area, then updated as balance changes after redemptions.
* Click & collect: a pickup pass is issued for the collection flow, then scanned in-store to release the order.

</details>

## Core omnichannel use cases

In most retail programs, wallet passes distributed from e-commerce are **account-linked**, not **order-linked**. The pass represents an ongoing relationship (loyalty, membership, stored value). It stays stable over time and updates when the customer profile changes.

Common patterns:

* **Loyalty / membership pass**: customer identifier + points + tier + benefits.
* **Wallet gift card**: stored value + barcode/QR for redemption + balance updates.
* **Customer recognition at POS**: scannable identifier that unlocks profile lookup and omnichannel attribution.
* **Pickup pass (pick & collect)**: order-linked, used when an in-store scan is required to release a prepared order.

## Where to place “Add to Wallet” in e-commerce

Placement should match the moment the pass becomes useful as an account credential. In practice, this is usually when a customer is authenticated, or when enrolment is completed.

{% stepper %}
{% step %}

### My Account / profile area (primary)

The account area is the most stable placement. It works for loyalty and membership, supports reinstall flows, and avoids linking the pass lifecycle to a single order.
{% endstep %}

{% step %}

### Post-registration / post-login moments (secondary)

After a signup or login, an “Add to Wallet” CTA can be shown as part of onboarding. This is often the highest-intent moment for new program members.
{% endstep %}

{% step %}

### Transactional email (fallback)

Email is useful as a recovery channel. It helps when the web CTA is missed, when purchase is completed on desktop, or when the customer changes device.
{% endstep %}

{% step %}

### Pick & collect pages (order-linked exception)

When the pass is used as a pickup token, the best placement is in the pick & collect flow (confirmation page and/or dedicated pickup page). This keeps order-linked passes limited to cases where an in-store scan is operationally required.
{% endstep %}
{% endstepper %}

## Updates and lifecycle (profile events → pass updates)

When profile data changes, the pass can be updated. Wallet apps can surface updates as native notifications. This keeps the pass trustworthy and reduces friction at the point of sale.

Typical update triggers in an omnichannel setup:

* Points and tier changes after purchase (online or in-store)
* Benefit eligibility changes (new perks, expired perks, special statuses)
* Gift card balance changes after redemption or reload
* Store preference changes (preferred store, local store list)
* Pick & collect status changes (ready, delayed, collected) when a pickup pass is used

{% hint style="info" %}
Wallet notifications are tied to an installed pass. They do not require a mobile app installation.
{% endhint %}

## Pass content checklist (what to include)

The pass should answer “who is this customer account” and “what is currently available”. Everything else belongs behind a link to authenticated pages.

Recommended fields:

* Brand name and support contact (email/phone/URL)
* Membership / loyalty identifier (visible + scannable barcode/QR when needed)
* Points balance, tier, and tier progress (when applicable)
* Benefit summary (what can be used in-store and online)
* Store list or store locator deep link (when relevant)
* Deep links (account page, loyalty dashboard, gift card management, customer service)

If a pick & collect pass is implemented, the pass typically adds:

* Pickup reference (not the full order)
* Pickup location and window
* Pickup QR/barcode used by staff

## Implementation with The Wallet Crew

E-commerce integration typically combines distribution, profile linkage, and in-store scanning:

1. Create (or retrieve) the pass from a stable customer identifier (CRM id, loyalty id, e-commerce customer id).
2. Expose an “Add to Wallet” CTA in the e-commerce account journey.
3. Connect POS scanning so the pass can be used for identification and redemption in-store.
4. Send profile events to The Wallet Crew so the pass stays current (points, tier, balances, benefits).

The same “Add to Wallet” button can be embedded on any brand-controlled website page when a stable identifier or pass identifier is available server-side.

### POS integration (what completes the omnichannel loop)

A wallet pass becomes the “missing link” between online and physical channels when it is scannable at the point of sale.

The common pattern is:

* the pass encodes a stable identifier in a barcode/QR (or a secure token resolved server-side)
* staff scan the pass at checkout
* the POS (or a connected loyalty/CRM layer) uses that identifier to retrieve the customer profile, apply benefits, and attribute the transaction

POS integrations are documented under [Point of Sale (POS)](https://docs.thewalletcrew.io/connectors/pos.md).

## How the Add to Wallet button works

This section owns the SDK explanation. The platform guides below link here and describe only what differs.

The browser SDK (called `cinto` in its script path and API) renders the right call to action for the device. On iOS, the button downloads an Apple Wallet pass. On Android, it opens Google Wallet. On desktop, it redirects to a hosted pass page that can be scanned or opened on a phone.

The SDK retrieves or creates a pass from three values:

* a **pass template** (`passType`, example: `user`)
* an **external identifier**: a key such as `sfcc.customerNo` and the stable value of the logged-in customer
* an **HMAC** signature of that value, which proves that the brand backend issued the identifier

Rules that apply to every storefront:

* Compute the HMAC server-side with the tenant secret. Never compute it in the browser, and never render the secret in HTML. Only the HMAC reaches the storefront. (The Shopify Liquid snippet is an exception, with its own risk: see [Shopify](https://docs.thewalletcrew.io/connectors/e-commerce/shopify.md#liquid-code-snippet-without-the-app).)
* Include the SDK loader once per page. When a page has several buttons, load it in a shared partial and repeat only the button markup.
* Do not cache customer-specific pages or fragments across customers. Check page cache, reverse proxy and CDN.
* If the storefront sends a Content Security Policy, allow `https://sdk.neostore.cloud` in `script-src`.
* Keep identifier keys stable and namespaced (`magento.customerId`). Changing a key on a live tenant is a migration.

The tenant secret is a general secret of The Wallet Crew: **Secret 1** or **Secret 2**, in **Settings → Access control → API keys & secrets**, **General secrets** tab. The platform accepts an HMAC computed with either secret. To rotate, set the new value in the secret the storefront does not use, switch the storefront to it, then replace the old secret.

For generic SDK usage (pass id mode, platform detection, desktop QR customization), see [On your website](https://docs.thewalletcrew.io/guides-enrolment/enrolment/on-your-website.md).

The prefix `neostore` is the platform's former name and is kept in technical identifiers. The SDK attributes (`data-neostore-*`), the script address (`sdk.neostore.cloud`) and the `neostore.cinto.initialize` call are real names and must be written as shown.

Attribute names are lowercased by the browser. In a `data-neostore-externalIdentifiers-<key>-value` (or `-hmac`) attribute, an underscore followed by a letter is read as that letter in uppercase: `customer_Id` and `customer_id` are both read as `customerId`. Write each uppercase letter of the key with an underscore before it, for example `sfcc.customer_No` for the key `sfcc.customerNo`. The escape applies to the attribute name only, not to the signed value.

A key that must contain an underscore cannot be passed as an attribute: pass it in the `externalIdentifiers` option of `neostore.cinto.initialize()` instead, for example `{ externalIdentifiers: { "sfcc.customer_no": { value: "...", hmac: "..." } } }`.

Validate any storefront integration the same way:

1. On iOS Safari, the button reads **Add to Apple Wallet**.
2. On Android Chrome, it reads **Add to Google Wallet**.
3. On desktop, it redirects to a hosted pass page.
4. After installation, the pass is visible in Apple Wallet or Google Wallet.

The diagram shows how the storefront signs the identifier before the browser asks for the pass.

```mermaid
sequenceDiagram
    participant B as Browser
    participant S as Storefront server
    participant T as The Wallet Crew
    B->>S: Request the account page
    S->>S: Sign the customer identifier with the tenant secret
    S-->>B: Page with the button, identifier and HMAC
    B->>T: SDK loads and sends identifier and HMAC
    T-->>B: Apple Wallet or Google Wallet pass
```

### Troubleshooting

#### The button does not render

Common causes are a blocked SDK script (CSP) or missing markup. The final HTML should contain the SDK loader and the SDK container element (`<div data-neostore-addToWalletButton ...>`).

#### Clicking the button leads to an error

This usually means the external identifier or HMAC does not match what The Wallet Crew expects. Confirm:

* the external identifier key name matches the one configured for the tenant
* the identifier value matches exactly what is signed server-side (no trimming, formatting, or type changes)
* the HMAC was computed with the correct tenant secret

#### The button renders for the wrong customer

This typically indicates HTML caching across sessions. Ensure that:

* customer-specific pages are not cached at page level
* remote includes or fragments used for account widgets are not cached across customers
* any reverse proxy or CDN respects session cookies for authenticated pages

## E-commerce platform guides

Use the platform-specific guides below when a storefront integration is required (typically in account pages or authenticated areas).

| Platform                                                                                                      | Integration style                                                                | Where the HMAC secret lives                                                                                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Shopify](https://docs.thewalletcrew.io/connectors/e-commerce/shopify.md)                                     | App theme block, or the Liquid snippet from the connector's **Code snippet** tab | The snippet signs `customer.id` in Liquid with the tenant general secret, embedded in the theme (see the warning on the [Shopify](https://docs.thewalletcrew.io/connectors/e-commerce/shopify.md#liquid-code-snippet-without-the-app) page) |
| [Salesforce Commerce Cloud](https://docs.thewalletcrew.io/connectors/e-commerce/salesforce-commerce-cloud.md) | Cartridge with a controller and an ISML partial                                  | Site preference of type Password                                                                                                                                                                                                            |
| [Adobe Commerce (Magento)](https://docs.thewalletcrew.io/connectors/e-commerce/adobe-commerce-magento.md)     | Module with a layout, a block and a PHTML template                               | `app/etc/env.php` or an environment variable                                                                                                                                                                                                |
| [PrestaShop](https://docs.thewalletcrew.io/connectors/e-commerce/prestashop.md)                               | Module or theme override                                                         | Environment variable or module configuration                                                                                                                                                                                                |

For in-store scanning with Shopify POS, see [Shopify POS](https://docs.thewalletcrew.io/connectors/pos/shopify-pos.md).

### E-commerce platforms not listed

See [Integrate software without a listed connector](https://docs.thewalletcrew.io/connectors/wallet-pass-connectors.md). For a custom storefront, use a [custom connector](https://docs.thewalletcrew.io/connectors/custom-connector.md): tenant scripting can call the storefront API and create, retrieve, or update passes.

## FAQ

<details>

<summary><strong>Is “Add to Wallet” only relevant for tickets or boarding passes?</strong></summary>

No. Wallet passes work well as customer credentials. Common examples include loyalty and membership cards, wallet gift cards, pickup confirmations, and service bookings.

</details>

<details>

<summary><strong>Can the same approach be used for gift cards?</strong></summary>

Yes. The same pattern works when the gift card is issued as a pass template in The Wallet Crew and a stable gift card identifier exists in the storefront (or in a connected system). The account area can render a button for each gift card by switching `data-neostore-passType` and the external identifier key and value to the gift card identifier, then signing that identifier with HMAC server-side.

</details>

<details>

<summary><strong>Can the button be displayed somewhere else than the account page?</strong></summary>

Yes. The same SDK can be used on any authenticated page where a stable identifier is available server-side. Common examples include a gift card list page, a loyalty dashboard, or a pick & collect page when a pickup pass is used as an in-store scan token.

</details>

<details>

<summary><strong>Can a pass be updated after it is added?</strong></summary>

Yes. Pass data can be updated after installation. Customers can also receive a wallet notification when an update occurs, depending on platform behavior and configuration.

</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/e-commerce.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.
