> 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/marketing-automation/bloomreach/bloomreach-activities.md).

# Bloomreach activities

Use Bloomreach scenarios to create, update, and notify Apple Wallet and Google Wallet passes managed in The Wallet Crew.

Bloomreach activities are scenario steps that call The Wallet Crew APIs. They turn a CRM decision (who/when/what) into a wallet action (create, update, notify).

## Activity catalog

These activities are typically created in Bloomreach as **Webhook preset** integrations. Each activity calls one The Wallet Crew endpoint.

HTTP authentication setup is covered in [Setup](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/setup.md). Each activity below gives its install payload, written in the Bloomreach WebHook preset parameter syntax. Install only the activities you need: it keeps scenario building simple and reduces configuration drift. One Bloomreach integration is typically created per activity.

The endpoint URLs below use `<host>` (see [Environments and URLs](https://docs.thewalletcrew.io/connectors/marketing-automation.md#environments-and-urls)) and `<<tenantId>>`: replace `<<tenantId>>` with the tenant identifier. API details: [API reference](https://docs.thewalletcrew.io/api-reference/).

Activity icons are available as a file:

{% file src="/files/det635CbJmRMpqPL1rJ8" %}

### Notify

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-d859e669434945910ba0ae9f246c87a021ea8eb3%2Fdocumentation-bloomreach-notify%20(1).png?alt=media" alt="Bloomreach activity icon: Notify" width="188"><figcaption><p>Icon to use when installing the Notify activity in Bloomreach.</p></figcaption></figure>

Notify sends a wallet message to a pass. On Apple Wallet, the message is delivered as a lock‑screen notification. On Google Wallet, the message appears on the pass.

{% hint style="warning" %}
Wallet notifications feel system-level. Overuse can hurt trust and opt-in rates.
{% endhint %}

<details>

<summary><strong>Install payload (Notify)</strong></summary>

Endpoint URL:

```
PUT https://<host>/api/<<tenantId>>/passes/notification?id=[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target', isJsonParam: true} : string]]
```

Example payload (single language):

```json
{
  "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', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : boolean | false]],
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload (localized):

```json
{
  "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', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : boolean | false]],
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

`correlationId` is optional, but when it is sent it must be 10 to 100 characters long, otherwise the call is refused (400). The same rule applies to the Apply benefit payload. Remove the `correlationId` line from the payload if the scenario does not set it.

</details>

### Apply benefit

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-73868795c9de7196559f27ac56f510eff1b44ca2%2Fdocumentation-bloomreach-apply-privilege.png?alt=media" alt="Bloomreach activity icon: Apply benefit" width="188"><figcaption><p>Icon to use when installing the Apply benefit activity in Bloomreach.</p></figcaption></figure>

Apply benefit attaches a benefit to a pass. That benefit can be a coupon, an access right, or a perk.

Benefits are first-class objects in The Wallet Crew. They can be displayed on the pass and tracked over time.

Apply benefit fits benefits with a lifecycle (availability, expiry, redemption). For the full concept, see [Benefit templates](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/benefit-templates.md).

<details>

<summary><strong>Install payload (Apply benefit)</strong></summary>

Endpoint URL:

```
POST https://<host>/api/<<tenantId>>/passes/[[ {name: 'passId', tooltip: 'Identifier of the pass', category: 'Pass target', isJsonParam: true} : string]]/benefits
```

{% hint style="info" %}
Activities installed with the former endpoint `POST .../passes/<passId>/privileges` still work, but that endpoint is deprecated. Install new activities with the `/benefits` endpoint and the payload below.
{% endhint %}

Payload example (unlocalized benefit):

```json
{
  "type": "multiUse",
  "origin": {
    "generator": "bloomreach",
    "processId": "[[ {name: 'Process identifier', tooltip: 'Identifier of the scenario / campaign', category: 'Advanced configuration', orderIndex: 120, isJsonParam: true} : string]]"
  },
  "priority": [[ {name: 'Priority', tooltip: 'High values mean stronger priority', category: 'Advanced configuration', orderIndex: 110, isJsonParam: true} : number]],
  "content": {
    "title": {
      "value": "[[ {name: 'Title', tooltip: 'Title of this benefit', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]"
    },
    "description": {
      "value": "[[ {name: 'Description', tooltip: 'Description of this benefit', category: 'Content', orderIndex: 20, isJsonParam: true} : string]]"
    }
  },
  "appearance": {
    "images": [
      {
        "slot": "main",
        "url": {
          "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 actions', category: 'Advanced configuration', orderIndex: 130, isJsonParam: true} : string]]"
  }
}
```

The payload also accepts `activationDate`, `deactivationDate` and `deletionDate` (date and time). Without them, the benefit is active at once, never expires and is never removed from the pass. A pass carries at most 20 benefits until their deletion date, so set a `deletionDate` for time-limited offers.

`origin.processId` makes the call idempotent: a second call with the same `processId` for the same pass updates the benefit instead of adding another. The response returns the `benefitId` of the written benefit.

</details>

### Update pass

<figure><img src="https://3852727835-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FlP7d71aYydav6e0pRkxc%2Fuploads%2Fgit-blob-b530369aa00a8d308d32bade799037acbf8024ca%2Fdocumentation-bloomreach-update-pass.png?alt=media" alt="Bloomreach activity icon: Update pass" width="188"><figcaption><p>Icon to use when installing the Update pass activity in Bloomreach.</p></figcaption></figure>

Update pass refreshes a pass so it reflects the latest data. This is the primary activity used to keep the pass accurate.

Typical updates include points, tier, balance, expiry, seat, venue, and instructions.

<details>

<summary><strong>Install payload (Update pass)</strong></summary>

Endpoint URL:

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

Minimum payload (options only):

```json
{
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload to update `additionalData`. The key `bloomreach_message` is an illustrative name: choose your own key, and make a field of the pass template read it with `{{ additionalData.bloomreach_message }}`.

```json
{
  "additionalData": {
    "bloomreach_message": "[[ {name: 'Message', tooltip: 'Message shown on the pass', category: 'Content', orderIndex: 10, isJsonParam: true} : string]]"
  },
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

Example payload to change the pass template (`passType`):

```json
{
  "passType": "newTemplate",
  "options": {
    "correlationId": "[[ {name: 'Correlation Id', tooltip: 'Grouping identifier to associate multiple actions', category: 'Advanced configuration', orderIndex: 20, isJsonParam: true} : string]]"
  }
}
```

</details>

### Add benefit movement (advanced, on request)

This activity updates a counter on an existing benefit. This is mainly used for punch cards, “progress to reward”, or multi-entry packs.

{% hint style="warning" %}
This activity is advanced and available on request. It usually requires a POS, scanner, or app to emit earn/spend signals.
{% endhint %}

The activity calls `POST https://<host>/api/<<tenantId>>/passes/benefits/<benefitId>/movements`. The body carries `oldValue` (the balance as last read; the movement is refused with 409 if the balance changed since), `value` (a signed whole number: positive credits, negative redeems) and optional `remarks`. The `benefitId` is returned by Apply benefit. The Bloomreach install payload is provided on request.

### Create pass (advanced, on request)

Create pass generates a new pass and returns its identifier. This is useful when Bloomreach is the orchestration layer and a pass does not exist yet.

The activity calls `POST https://<host>/api/<<tenantId>>/passes?passType=<pass template>` with the pass identifiers and `additionalData` in the body. The Bloomreach install payload is provided on request.

## FAQ

<details>

<summary><strong>What’s the difference between Update pass and Notify?</strong></summary>

Update pass changes what is displayed on the pass. Notify is a delivery mechanism meant to bring attention.

In most time-sensitive flows, Update pass runs first, then Notify.

</details>

<details>

<summary><strong>When is Apply benefit better than Update pass?</strong></summary>

Apply benefit fits benefits with a lifecycle. Examples include vouchers, access rights, and offers that expire.

Update pass fits state values. Examples include points, tier, and balance.

</details>

<details>

<summary><strong>Where does the pass identifier (passId) come from in Bloomreach?</strong></summary>

The pass identifier can be stored as a Bloomreach customer property. It can also be captured from The Wallet Crew events sent to Bloomreach.

</details>

<details>

<summary><strong>What happens if the pass is not installed, and how do I test in staging?</strong></summary>

See the guards in [Recipes](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/recipes.md#guard-against-non-installed-passes) and the staging test run in [Recipes](https://docs.thewalletcrew.io/connectors/marketing-automation/bloomreach/recipes.md#faq).

</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/marketing-automation/bloomreach/bloomreach-activities.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.
