Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Real-world examples
  • 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.

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.

1

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.

2

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.

3

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.

4

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.

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

Wallet notifications are tied to an installed pass. They do not require a mobile app installation.

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).

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.)

  • 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.

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.

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

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 page)

Cartridge with a controller and an ISML partial

Site preference of type Password

Module with a layout, a block and a PHTML template

app/etc/env.php or an environment variable

Module or theme override

Environment variable or module configuration

For in-store scanning with Shopify POS, see Shopify POS.

E-commerce platforms not listed

See Integrate software without a listed connector. For a custom storefront, use a custom connector: tenant scripting can call the storefront API and create, retrieve, or update passes.

FAQ

Is “Add to Wallet” only relevant for tickets or boarding passes?

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

Can the same approach be used for gift cards?

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.

Can the button be displayed somewhere else than the account page?

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.

Can a pass be updated after it is added?

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.

Last updated