> 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/guides-animation/engage-and-animate/geolocated-notifications.md).

# Geolocated notifications

Surface a pass message when a customer is near a configured store or venue, and set up the message in the admin console.

Geolocated notifications show a contextual message near a location. Apple Wallet or Google Wallet can surface it when a customer is nearby. Use it for reminders (“don’t forget your card”) and on-site information (“gate changed”).

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-24d1665f78605bf7581670fe0a93ffa5a0657f0d%2Fgeolocated-notification-phone-example-clean-labels.png?alt=media" alt="A geolocated wallet notification shown on a phone, with a map and a concert hall in the background"><figcaption><p>Check that the message reads clearly at a glance, since it appears on the lock screen.</p></figcaption></figure>

This works for **stores and any venue**. Typical venue examples are stadiums, concert halls, theaters, and pop-ups.

<details>

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

* Remind loyalty members to scan their card at checkout.
* Display a voucher reminder only if a voucher is available.
* Announce a store opening to customers near that location.
* Remind ticket holders of gate/door info when approaching the venue.
* Surface a “your ticket is ready” message near the venue entrance.

</details>

{% hint style="info" %}
Geolocated notifications appear only if the customer enables location features for their wallet app.

On iOS: **Settings → Privacy & Security → Location Services → Wallet**.

On Android: check Google Wallet permissions in the device **Settings** (location must be allowed).
{% endhint %}

## How it works

Wallet passes can store a small set of “relevance” locations. The phone compares the device position to those locations. When the customer enters the configured radius, the wallet app can surface the pass and its message.

The Wallet Crew fills these locations from the tenant's stores, in **Data & integrations → Data stores**. See [How The Wallet Crew selects locations per customer](#how-the-wallet-crew-selects-locations-per-customer). For venues, the venue is usually modeled as a store so it can be geolocated the same way.

### What customers will see (varies by platform)

{% tabs %}
{% tab title="Apple Wallet (iOS)" %}
iOS can surface a lock screen suggestion when the customer is near one of the configured locations. The suggestion can include the message configured on the template.
{% endtab %}

{% tab title="Google Wallet (Android)" %}
Android can surface a “nearby pass” experience when the customer is near one of the configured locations. The exact UI depends on Android version and device manufacturer. It does not show the message written in The Wallet Crew.
{% endtab %}
{% endtabs %}

### Limits to design for

These platform limits apply:

* Up to **10 locations** per pass, on both wallets.
* The radius is set by the wallet, with no guarantee. Apple Wallet uses the smaller of the template's **Max distance** and its own default distance, which is around 250 m and controlled by Apple. Google Wallet uses a radius set by Google.

Message visibility is controlled by the OS. In practice, the message can remain visible while the customer stays in the area. The OS typically surfaces the message when the customer enters the configured area, can remove it when they leave, and can show it again the next time they enter. See Apple's [Showing a pass on the lock screen](https://developer.apple.com/documentation/walletpasses/showing-a-pass-on-the-lock-screen).

### Geolocation vs “push notifications”

Geolocated notifications are not “sent” at a specific time by The Wallet Crew. They are triggered by the customer’s phone when it detects proximity.

For a server-triggered message, use standard wallet notifications instead. Start with [Push notifications](/guides-animation/engage-and-animate/automatisation/push-notifications.md) and the recipe [Send a one-off notification](/guides-animation/engage-and-animate/automatisation.md#send-a-one-off-notification).

## Prerequisites

Locations must be configured in The Wallet Crew. Each store needs a latitude and a longitude. The address is shown to the holder but is not used to place the store.

Venues are modeled as stores too. Example: create a store entry for `Stadium - Gate A` or `Concert hall - Main entrance`.

Locations are managed in **Data & integrations → Data stores**. When stores are not set up yet, start with [Stores](/configure/advanced-configuration/platform/data-and-integrations/stores.md).

<div data-with-frame="true"><figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-5de7f35f8ce0d6450d60f7fcb594e5a0151f5660%2Fdata-stores-form-retake.png?alt=media" alt="New store form in Data &#x26; integrations → Data stores, with the address and the coordinates"><figcaption><p>Each store carries its own coordinates (stores or venues).</p></figcaption></figure></div>

## Set up the message in The Wallet Crew

Configure the message for a pass template. Use Liquid for personalization.

{% stepper %}
{% step %}

### Open Geofenced messages

Open **Engagement → Geofenced messages** and choose the pass template.
{% endstep %}

{% step %}

### Write the message

Write the message in **Content (multilingual)**. Add Liquid variables if needed. Keep it short: aim for 120 characters or fewer, as the **Recommended length** counter shows. Longer text is allowed.

<figure><img src="https://2685221786-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F97ZAXMtqOjhvBBCfpmcE%2Fuploads%2Fgit-blob-c779c1d24b438908a0068c3a3cd4387034f77ab0%2Fgeofenced-messages-editor-clean.png?alt=media" alt="Geofenced messages editor with the language tabs, the message field and the notification preview"><figcaption><p>The geofenced message editor of a pass template, with the notification preview.</p></figcaption></figure>
{% endstep %}

{% step %}

### Configure translations (optional)

When the template is translated, pick each language in the language selector above the field and write the message for it.
{% endstep %}

{% step %}

### Save and test

Click **Save**. Saving updates the pass template and pushes an update to every pass of that template.

Then test with a device near a configured location. Validate both the location behavior and the Liquid rendering.
{% endstep %}
{% endstepper %}

## How The Wallet Crew selects locations per customer

The location selection logic depends on the use case. Loyalty programs typically rely on “home store” logic. Event tickets typically rely on the venue location assigned to the pass.

For a retail-style setup, the pass gets the **10 stores nearest to the holder**:

* When the holder's country and postcode are known, the stores nearest to that postcode.
* Otherwise, the stores nearest to the holder's own store (the home store), which then comes first.

## Automatic updates of location coordinates

When a pass update is performed via The Wallet Crew, the list of nearest stores is recalculated when the holder's store, country or postcode changes. Stores added later can become one of the nearest stores.

## Locations in the template editor

The **Apple** tab (**Locations** and **Beacons**) and the **Google** tab (**Locations**) of the pass template editor also hold locations: a label, a latitude and a longitude, and on Apple an altitude and a **Max distance**. See [Locations and beacons](/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#locations-and-beacons) and the [Google tab](/configure/advanced-configuration/wallet/template-configuration/google-tab.md).

Locations entered by hand in the template (a fixed latitude) are kept when you save a geofenced message. The store locations fill the remaining slots, up to 10 in total.

## Liquid examples for geolocated notification messages

Use Liquid to personalize the message or show it only to relevant customers. The store data on the pass has these fields:

* `data.store.*`: the store the customer is near. Saving the message points each `{{data.store.…}}` output at the store of its own location. A `data.store` reference inside a Liquid condition is not repointed and always reads the nearest store.
* `data.associatedStore.*`: the holder's own store.

Both carry `storeId`, `displayName`, `address`, `latitude`, `longitude`, and `altitude` when set.

{% code title="Example 1 — name the store" %}

```liquid
Welcome to {{data.store.displayName}}. Don’t forget to scan your loyalty card at checkout.
```

{% endcode %}

{% code title="Example 2 — store-specific message" %}

```liquid
{%- if data.associatedStore.storeId == "STORE-A" -%}
Your store has moved. Visit our new address nearby.
{%- else -%}
Welcome back. Your store is nearby. Come discover our latest arrivals.
{%- endif -%}
```

{% endcode %}

## FAQ

<details>

<summary><strong>Can we track how many customers received the geolocated message, or who is inside the store?</strong></summary>

No. This is not a message that The Wallet Crew actively sends at a given time. The customer’s phone triggers it locally when it gets near the configured coordinates, and geolocation triggers do not send “entered” or “in-store” events back to The Wallet Crew.

</details>

<details>

<summary><strong>Why didn’t the geolocated notification show up on a phone?</strong></summary>

Start with the phone settings listed at the top of this page.

Then validate the pass data. The pass must include location coordinates, and the customer must be close enough to the configured radius.

</details>

<details>

<summary><strong>Is this the same as beacon-based notifications?</strong></summary>

No. Beacons use Bluetooth (iBeacon identifiers). Geolocated notifications use GPS coordinates.

Apple Wallet also supports beacon triggers. Before using them, confirm the target devices and store hardware constraints.

</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/guides-animation/engage-and-animate/geolocated-notifications.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.