Bloomreach

Wallet Crew × Bloomreach Integration Documentation

What this integration does

Sync Wallet passes (Apple Wallet + Google Wallet) with Bloomreach Engagement.

You get three things:

1. Bloomreach actions that update passes in real time.

2. Wallet Crew events sent to Bloomreach, so scenarios react to wallet behavior.

3. Wallet Crew components that read/write Bloomreach customer data.

Bloomreach activities

Use these activities in Bloomreach scenarios. They update wallet passes.

Most common

• Notify: send a wallet notification (optionally refresh the pass too).

• Apply privilege: attach an offer/benefit to the pass and update visuals and content.

Advanced

• Update pass: refresh pass content (tier, points, expiry, etc.).

• Add privilege movement: increment/decrement a trackable privilege value.

• Create pass: create a new pass and return a download link.

Notify

Send a push-style message that appears on the lock screen. Use it for time-sensitive moments. Keep it rare.

If you want the pass to show new content (coupon code, new instruction, new tier), combine Notify with Apply privilege or Update pass.

Real-world examples

• Retail: Birthday message: “Happy birthday! Enjoy 20% off today.” Then the customer opens the pass to see the offer.

• Events: “Your event starts in 2 hours. Gate opens at 7 PM.” Use it to reduce no-shows.

• Fitness: Re-engagement: “You haven’t visited in 2 weeks. We miss you.” Pair it with a perk for better conversion.

Apply privilege

Add a benefit to the pass (offer, perk, access, voucher). It can also change pass visuals, so customers notice.

Use Apply privilege when you want a clear benefit on the pass. Privileges are a first-class object in Wallet Crew. See Privilege.

Real-world examples

• Retail: “VIP Weekend” privilege. Pass turns gold. Text says “2× points this weekend”. Optional notify: “You’ve been upgraded.”

• Fitness: “Bring a friend” privilege. Pass shows a guest entry that expires in 7 days.

• Events: “Fast lane entry” or “VIP lounge access” privilege for a subset of ticket holders.

Update pass

Refresh the pass so it reflects the latest data (from Bloomreach and your other systems).

This is your “keep the pass accurate” activity. This activity is very powerfull and has many options.

Real-world examples

• Retail loyalty: After a purchase, update the pass so points, tier, and next-reward progress are correct.

• Events: Seat change, schedule update, venue change, updated entry instructions.

• Membership: Membership renewal, expiry date change, status changes (active/paused).

Add privilege movement

This is an advanced feature. Most teams don't use it.

Track a changing balance on an existing privilege (earn / spend / progress). Most marketers won’t need this unless you run punch cards, counters, or “progress to reward”.

Real-world examples

• Coffee stamps: Customer buys a drink → +1 stamp. At 10 stamps, the reward becomes redeemable.

• Multi-entry packs: Gym has “10 entries”. Each check-in consumes 1 entry.

• Birthday gift: Add +1 “free entry” to a guest-pass privilege. When redeemed, it goes back down.

This usually requires your POS / scanner / app to send the earn-and-redeem signals.

Create pass

This is an advanced feature. Most teams don't use it.

Create a new pass for a customer and get an “add to wallet” link you can distribute. Use it when the customer doesn’t have a pass yet.

Real-world examples

• Retail: After signup, create a loyalty card pass. Send the add-to-wallet link by email/SMS. Once installed, apply a “Welcome offer” privilege.

• Events: After ticket purchase, create a ticket pass. Send the link in the confirmation email. Then notify reminders before the event.

• Membership: New member joins a club. Create the membership card pass. Show tier/status and expiry on the pass.

Wallet Crew components

Configuration screen

Configure the Bloomreach connection in the Wallet Crew back-office.

Set your API Key & Secret (project access), your Project Token (environment), and the Base URL (API endpoint).

Events

These events are sent from Wallet Crew to Bloomreach.

Event Name	When It Fires	Key Data Included
Pass:Created	When a new wallet pass is generated	Pass type, customer identifiers, creation timestamp, metadata
Pass:Installed	When customer adds pass to their wallet (Apple/Google)	Device type, installation source, registration count, campaign tracking data
Pass:Uninstalled	When customer removes pass from wallet	Device type, total registration count, active registration count
Pass:Scanned	When pass barcode/QR code is scanned	Scanned data, scan type, location information

Event Data Structure

Each event includes:

• Pass Information: Pass type, pass ID, serial number

• Customer Identifiers: Email, member ID, external IDs

• Metadata: Custom data fields associated with the pass

• Device Context (where applicable): Apple Wallet vs Google Wallet

• Tracking Data (where applicable): Campaign source, UTM parameters, registration tags

Event Data Properties

All events are sent as flat key/value properties to Bloomreach.

Two property names are patterns:

• identifier_xxx: one property per pass identifier (email, memberId, etc.).

• metadata_xxx: one property per metadata key stored on the pass.

When a source key contains ., it is normalized to _ in the property name. Example: identifier key y2.customerId becomes identifier_y2_customerId.

Pass:Created

Fires when Wallet Crew generates a new pass. This is mainly useful for debugging, auditing, or “pass created but not installed yet” technical flows.

Event Name : wallet_created

Properties :

Property name	Description
passId	Wallet Crew pass identifier. Use it to reference the pass in Wallet Crew APIs and logs.
passKind	High-level pass category: customerCard, eventTicket, giftCard, offer, or generic.
passType	Pass template name used to create the pass (your Wallet Crew template identifier).
identifier_xxx	External identifiers attached to the pass (one property per identifier). If an identifier key contains ., it is replaced by _ in the property name. Example: identifier_y2_customerId. All identifiers present on the pass are sent.
metadata_xxx	Custom pass metadata (one property per metadata key).

Pass:Installed

Fires when a customer adds the pass to Apple Wallet or Google Wallet. It can fire multiple times for the same pass (re-install, multiple devices).

Event Name : wallet_installed

Properties :

Property name	Description
passId	Wallet Crew pass identifier. Use it to reference the pass in Wallet Crew APIs and logs.
passKind	High-level pass category: customerCard, eventTicket, giftCard, offer, or generic.
passType	Pass template name used to create the pass (your Wallet Crew template identifier).
identifier_xxx	External identifiers attached to the pass (one property per identifier). If an identifier key contains ., it is replaced by _ in the property name. Example: identifier_y2_customerId. All identifiers present on the pass are sent.
metadata_xxx	Custom pass metadata (one property per metadata key).
device	Wallet platform where the pass was installed: apple or google.
registrationInformation_totalRegistrationCount	Total number of installs recorded for this pass (lifetime), after this install.
registrationInformation_activeRegistrationCount	Number of active installations currently recorded for this pass, after this install.
registrationSource_medium	Tracking medium captured during installation (e.g., email, sms, qr, in_app). Provided by your add-to-wallet link tracking.
registrationSource_tags	Tracking tags captured during installation (values you attach to the add-to-wallet link or install flow).
registrationSource_userAgent	User agent string of the device/browser that initiated the installation.
registrationSource_origin	Origin URL where the installation started (landing page or referrer captured by Wallet Crew).

Pass:Uninstalled

Fires when a customer removes the pass from their wallet app. Use it for churn signals and win-back automation.

Event Name : wallet_uninstalled

Properties :

Property name	Description
passId	Wallet Crew pass identifier. Use it to reference the pass in Wallet Crew APIs and logs.
passKind	High-level pass category: customerCard, eventTicket, giftCard, offer, or generic.
passType	Pass template name used to create the pass (your Wallet Crew template identifier).
identifier_xxx	External identifiers attached to the pass (one property per identifier). If an identifier key contains ., it is replaced by _ in the property name. Example: identifier_y2_customerId. All identifiers present on the pass are sent.
metadata_xxx	Custom pass metadata (one property per metadata key).
device	Wallet platform that reported the uninstall: apple or google.
registrationInformation_totalRegistrationCount	Total number of installs recorded for this pass (lifetime), after this uninstall.
registrationInformation_activeRegistrationCount	Number of active installations currently recorded for this pass, after this uninstall.

Pass:Scanned

Fires when the pass barcode / QR code is scanned. This is your best “in-store / at-venue” behavioral signal.

For this event to be triggered, the Scan API needs to be invoked.

Event Name : wallet_scanned

Properties :

Property name	Description
passId	Wallet Crew pass identifier. Use it to reference the pass in Wallet Crew APIs and logs.
passKind	High-level pass category: customerCard, eventTicket, giftCard, offer, or generic.
passType	Pass template name used to create the pass (your Wallet Crew template identifier).
identifier_xxx	External identifiers attached to the pass (one property per identifier). If an identifier key contains ., it is replaced by _ in the property name. Example: identifier_y2_customerId. All identifiers present on the pass are sent.
metadata_xxx	Custom pass metadata (one property per metadata key).
scannedData	Raw value decoded from the barcode/QR code at scan time (what your scanner captured).
scannedType	Barcode/QR format used for the scan (symbology). Exact values depend on the scanner integration.

How to Use These Events in Bloomreach

Engagement & re-engagement: Use Pass:Installed to trigger a welcome series for new members. Use Pass:Uninstalled for win-back campaigns. Use the absence of Pass:Installed for follow-ups reminding customers to add their pass.

Behavioral triggers: Send a post-visit survey after Pass:Scanned. Combine Pass:Scanned with purchase data for recommendations. Reward loyal visitors who scan often.

Privilege-based campaigns: Notify on Privilege:Created to surface new offers. Use Privilege:MovementApplied to show progress toward rewards. Re-engage when privileges expire or are removed via Privilege:Deleted.

Lifecycle marketing: Combine Pass:Created and Pass:Installed. Remind after 48 hours if the pass isn't installed. Re-engage when a pass hasn't been scanned in 30 days. Detect VIPs from repeated Pass:Scanned events.

PassDataProvider

Retrieve and display customer information from Bloomreach directly on wallet passes. You can display customer tier levels (Gold, Silver, Bronze) on loyalty cards, show membership expiry dates, display accumulated points or rewards balances, and showcase personalized offers based on Bloomreach customer data.

The Pass Data Provider supports scripting. You can control which Bloomreach attributes appear on the pass, and how they are formatted.

Example: show tier and points from Bloomreach. Refresh when the customer opens the pass.

CustomerFlowElement

Automatically create or update customer profiles in Bloomreach when customers register through your wallet pass forms. When a customer submits a registration form (e.g., signing up for a new loyalty card), this component searches for existing customers in Bloomreach, creates a new profile if the customer doesn't exist, or updates the existing profile if found. It includes scripting extensibility to customize how customers are matched by email, phone number, member ID, or other identifiers.

In retail scenarios, a customer signing up for a loyalty card creates a profile in Bloomreach and immediately receives welcome email campaigns. For fitness centers, new gym members register, their profile syncs to Bloomreach, and they're enrolled in onboarding email series. In the events space, ticket purchasers register, profiles are created, and they receive pre-event communications.

Setup

The Wallet crew configuration

1

Enable connector

Ask the Wallet Crew team to enable the Bloomreach connector for your tenant.

2

Configure general settings

Open the Bloomreach connector settings in the Wallet Crew back-office.

Open General settings page

Fill in Project Token, API Base Url, API Key Id, and API Secret.

Get these values in Bloomreach Engagement under Project settings → Access Management → API.

Make sure Project Token matches the environment you want to target (e.g., prod vs test).

3

Extensibility - Advanced configuration

You can override default connector behavior with scripts. Open the advanced settings page to customize each script.

Open Advanced settings page

Contact Finder

A pass is linked to external identifiers (for example: email, phone, member ID). When an event happens on a pass, the connector attaches it to a Bloomreach contact.

Use this extensibility point to change how Wallet Crew resolves the Bloomreach contact for a pass.

/**
 * Retrieve contact identifier from pass identifiers to determine the bloomreach contact of a pass.
 * Default implementation uses email as registered identifier
 *
 * This method is asynchronous, allowing calls to external webservices if needed.
 *
 * @param {Record<string, any>} identifiers - Key-value pairs of pass identifiers
 * @returns {Promise<Record<string, string>>} Object with 'registered' key containing the contact identifier on the bloomreach side
 */
async function getContactIdentifiers(identifiers) {
  // Example: use email as the contact identifier
  // this is the default implementation
  return { "registered": identifiers["email"] };
}

export default function (context) {
  context.register('extensions.bloomreach.contactFinder', {
    GetContactIdentifiers: getContactIdentifiers
  });
}

Event Interceptor

Intercept and change eventName and properties before sending the event to Bloomreach.

You can also drop an event by returning null.

/**
 * Intercept events before sending to Bloomreach.
 * Use this to transform event names or properties dynamically.
 * Example: Add calculated fields, rename properties, filter data
 *
 * @param {Object} eventData - Event data object
 * @param {string} eventData.Name - Name of the event being tracked
 * @param {Record<string, string>} eventData.Properties - Event attributes/metadata
 * @returns {Promise<Object>} Modified event data object - could be null to omit this event
 */
async function interceptEvent({ Name, Properties }) {
  // Example: return event as-is (no transformation)
  // Modify as needed for your use case
  return { Name, Properties };
}

export default function (context) {
  context.register('extensions.bloomreach.event.interceptor', {
    Intercept: interceptEvent
  });
}

Customer Mapper

Customize mapping between Wallet Crew enrollment form fields and Bloomreach fields (and vice versa).

This extensibility point is used only when data is sent to / retrieved from Bloomreach using PassDataProvider and CustomerFlowElement.

/**
 * Maps wallet crew account data to Bloomreach properties.
 *
 * @param {Object} account - The wallet crew account object with fields like firstName, email, etc.
 * @param {Object} properties - Bloomreach properties object to populate (mutated in place)
 */
function mapToBloomreach(account, properties) {
  // Example mappings - customize based on your field names
  if (account?.firstName) {
    properties["first_name"] = account.firstName;
  }
  if (account?.lastName) {
    properties["last_name"] = account.lastName;
  }
  if (account?.email) {
    properties["email"] = account.email;
  }
}

/**
 * Maps Bloomreach customer data to the wallet crew account fields.
 *
 * @param {Object} customer - Bloomreach customer object with Properties and Identifiers
 * @param {Object} account - The wallet crew account object to populate (mutated in place)
 */
function mapFromBloomreach(customer, account) {
  // Example mappings - customize based on your field names
  if (customer && customer.Properties) {
    if (customer.Properties["first_name"]) {
      account["firstName"] = customer.Properties["first_name"];
    }
    if (customer.Properties["last_name"]) {
      account["lastName"] = customer.Properties["last_name"];
    }
    if (customer.Properties["email"]) {
      account["email"] = customer.Properties["email"];
    }
  }
}

export default function (context) {
  context.register('extensions.bloomreach.mapper', {
    MapToBloomreach: mapToBloomreach,
    MapFromBloomreach: mapFromBloomreach
  });
}

Bloomreach configuration

1

Set up the connection

Bloomreach calls Wallet Crew APIs using an API key. You configure this once as an HTTP authentication schema in Bloomreach.

1. In Bloomreach, go to Data & Assets > Integrations, then click + Add new integration

1. Select Http Authentication Schemas

1. Configure the HTTP authentication schema

Generate a new API key in the Wallet Crew back-office. Grant it the tenant.pass:write permission.

Open API Keys Configuration

Fill the schema form with the following values:

Endpoint	https://app.neostore.cloud/api or https://app-qa.neostore.cloud/api for the staging environment
Type	Customer headers
Key	X-API-KEY
Value	{twc_api_key}

2

Add Webhook preset Activity

Create one Bloomreach integration per activity.

Import only the activities you need.

1. In Bloomreach, go to Data & Assets > Integrations, then click + Add new integration

1. Select WebHook preset.

1. Configure the WebHook preset.

Paste the endpoint URL from the activity you want to install. Then set the request body to match the payload examples below.

Import and configure only the activities you need.

Icons can be found here :

6KB

twc-bloomreach-icons.zip

archive

Open

Push Update

Updates an existing pass. When triggered, Wallet Crew rebuilds the pass and pushes the update to devices.

Endpoint URL:

PATCH https://app.neostore.cloud/api/<<tenantId>>/passes/?id=[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target',  isJsonParam: true} : string]]

Replace <<tenantId>> with your Wallet Crew tenantId.

Minimum payload (options only):

{
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : string]]",
  }
}

Payload example to update additionalData:

{
  "additionalData": {
    "xx": "[[ {name: 'xx', tooltip: 'xx', category: 'Content',  orderIndex:10, isJsonParam: true} : string]]",
    "xy": "[[ {name: 'xy', tooltip: 'xy', category: 'Content',  orderIndex:11, isJsonParam: true} : string]]",
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : string]]",
  }
}

Payload example to change the pass template (passType):

{
  "passType": "newTemplate",
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : string]]",
  }
}

You can combine these fields in a single call. See Update Pass API for more information.

Notify

Sends a wallet notification to a pass.

Endpoint URL:

PATCH https://app.neostore.cloud/api/<<tenantId>>/passes/notification?id=[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target',  isJsonParam: true} : string]]

Replace <<tenantId>> with your Wallet Crew tenantId.

Payload example (single language):

{
  "content": "[[ {name: 'Notification Content', tooltip: 'Content of the notification', category: 'Content',  orderIndex:10, isJsonParam: true} : string]]",
  "options": {
    "updateData": [[ {name: 'Update data', tooltip: 'Also update pass data when notification is sent - only activate if needed to improve performance', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : boolean | false]],
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : string]]",
   }
}

Payload example (localized):

{
  "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : string]]",
  "localizedContent": {
    "en": "[[ {name: 'Notification Content (en)', tooltip: 'Content of the notification', category: 'Content',  orderIndex:10, isJsonParam: true} : string]]",
    "fr": "[[ {name: 'Notification Content (fr)', tooltip: 'Content of the notification', category: 'Content',  orderIndex:11, isJsonParam: true} : string]]",
  }  
  "options": {
    "updateData": [[ {name: 'Update data', tooltip: 'Also update pass data when notification is sent - only activate if needed to improve performance', category: 'Advanced configuration',  orderIndex:20, isJsonParam: true} : boolean | false]]
  }
}

See notify API for more information.

Apply Privilege

Adds a privilege to a specific pass. See Privilege concept for details.

Endpoint URL:

POST https://app.neostore.cloud/api/<<tenantId>>/passes/[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target',  isJsonParam: true} : string]]/privileges

Replace <<tenantId>> with your Wallet Crew tenantId.

Payload for unlocalized privilege:

{
  "type": "multiUse",
  "origin": {
    "generator": "bloomreach",
    "processId": "[[ {name: 'Process identifier', tooltip: 'Identifier of the process emitting this privilege. It could be the name of the campaign for example. It also help monitoring', category: 'Advanced configuration', orderIndex:120, isJsonParam: true} : string]]"
  },
  "priority": "[[ {name: 'Priority', tooltip: 'High values means stronger prority', category: 'Advanced configuration',orderIndex:110, isJsonParam: true} : number]]",
  "content": {
   "title" : {
     "value": "[[ {name: 'Title', tooltip: 'Title of this privilege', category: 'Content', orderIndex:10, isJsonParam: true} : string]]"
   },
   "description": {
     "value": "[[ {name: 'Description', tooltip: 'Description of this privilege', category: 'Content', orderIndex:20, isJsonParam: true} : string]]"
   }
  },
  "appearance": {
   "mainImageUrl":{
     "value" : "[[ {name: 'Main Image', tooltip: 'Url of the main image', category: 'Content', orderIndex:30, isJsonParam: true} : image]]"
   }
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:130, isJsonParam: true} : string]]",
   }
}

Payload for localized privilege :

{
  "type": "multiUse",
  "origin": {
    "generator": "bloomreach",
    "processId": "[[ {name: 'Process identifier', tooltip: 'Identifier of the process emitting this privilege. It could be the name of the campaign for example. It also help monitoring', category: 'Advanced configuration', orderIndex:120, isJsonParam: true} : string]]"
  },
  "priority": "[[ {name: 'Priority', tooltip: 'High values means stronger prority', category: 'Advanced configuration',orderIndex:110, isJsonParam: true} : number]]",
  "content": {
   "title" : {
     "values": {
       "fr":"[[ {name: 'Title (fr)', tooltip: 'Title of this privilege', category: 'Content', orderIndex:10, isJsonParam: true} : string]]",
       "en":"[[ {name: 'Title (en)', tooltip: 'Title of this privilege', category: 'Content', orderIndex:10, isJsonParam: true} : string]]"       
     }
   },
   "description": {
     "values": {
       "fr" :"[[ {name: 'Description (fr)', tooltip: 'Description of this privilege', category: 'Content', orderIndex:20, isJsonParam: true} : string]]",
       "en" :"[[ {name: 'Description (en)', tooltip: 'Description of this privilege', category: 'Content', orderIndex:20, isJsonParam: true} : string]]",
     }
   }
  },
  "appearance": {
   "mainImageUrl":{
     "values" : {
       "fr":"[[ {name: 'Main Image (fr)', tooltip: 'Url of the main image', category: 'Content', orderIndex:30, isJsonParam: true} : image]]",
       "en":"[[ {name: 'Main Image (en)', tooltip: 'Url of the main image', category: 'Content', orderIndex:30, isJsonParam: true} : image]]"
     }
   }
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple action - setting the same correlationId allow cancellation of all the associated action within TWC back-office. It also help monitoring', category: 'Advanced configuration',  orderIndex:130, isJsonParam: true} : string]]",
   }
}

See notify API for more information.

Add Privilege Movement

Documentation will be available soon

See Apply Privilege API for more information

Create Pass

Documentation will be available soon

See Create pass API for more information

Best practices

Update vs notify

• Use Update when pass data must change (points, tier, expiry, ...).

• Use Notify when you need attention (deadline, reminder, urgent offer, ...).

• Use Apply Privilege when want to enhance the pass with additional information (promotion, benefit available, new message, ...)

Consent and frequency

Make notifications conditional on customer consent. Wallet notifications feel system-level. Overuse hurts trust.

More recommendations on consent capture and frequency limits will be available soon.

Support & links

• Privileges: Privilege

• Bloomreach docs: Bloomreach Engagement documentation