> 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-design/design/loyalty-card-template-configuration.md).

# Loyalty card

What is specific to a loyalty card pass template: layout, member ID barcode, points in the header, Google loyalty fields and the iOS 27 poster layout.

Use a loyalty card when the pass stands for an ongoing relationship with a customer: a member ID, a tier, a points balance and a barcode that the point of sale reads. In the admin console, this type is called **Customer card**. When the program only counts visits, a [stamp card](https://docs.thewalletcrew.io/guides-design/design/stamp-card.md) is simpler: the count lives on the pass and needs no external loyalty system (see [Pass types & templates](https://docs.thewalletcrew.io/guides-design/design/pass-types-and-templates.md#choose-the-right-pass-type)).

This page covers only what is specific to a loyalty card. Every setting is described in the [pass template editor](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration.md), which also explains how to save and push changes.

<details>

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

* A fashion brand uses a seasonal campaign visual as poster artwork, and changes it for the sales without touching the fields.
* A beauty loyalty program shows the member name and tier as summary fields, and the program name in the footer.
* A retailer adds a **View membership benefits** featured action that opens the benefits page, and an **Order delivery or pickup** action for click-and-collect orders.

</details>

## Layout of the two wallets

{% tabs %}
{% tab title="Apple" %}

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FBbjxTt8fWc17cmmKrPLy%2Fdesign-loyalty-card-architecture-apple.png?alt=media&#x26;token=a48c21a4-6fe5-4c82-bee7-f7b6f6d069d1" alt="Apple loyalty card layout with header, front and back field zones"><figcaption><p>Check where the header, front fields and back fields sit in the Apple loyalty layout.</p></figcaption></figure>
{% endtab %}

{% tab title="Google" %}

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FZzJJtHAUqB1AlBLK4nwB%2Fdesign-loyalty-card-architecture-google.png?alt=media&#x26;token=6b5e0766-d9ce-4bae-b173-821e8c10dd02" alt="Google loyalty card layout with points, account and messages areas"><figcaption><p>Check how Google splits the same loyalty card into points, account and messages areas.</p></figcaption></figure>
{% endtab %}
{% endtabs %}

<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td align="center">Apple pass</td><td data-object-fit="contain" data-alt="Apple example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F3HTF0raNps6AjxLdaCKK%2Fdesign-loyalty-card-apple-example-loyalty-card-3.png?alt=media&#x26;token=c5d95f71-bf9b-456b-b414-44d57d43441f">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F3HTF0raNps6AjxLdaCKK%2Fdesign-loyalty-card-apple-example-loyalty-card-3.png?alt=media&#x26;token=c5d95f71-bf9b-456b-b414-44d57d43441f</a></td></tr><tr><td align="center">Apple pass</td><td data-object-fit="contain" data-alt="Apple example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FB0yY4vj4GoA5t4pJuSCH%2Fdesign-loyalty-card-apple-example-loyalty-card-2.png?alt=media&#x26;token=983317c6-bc3d-4abc-a0ff-822e167d5425">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FB0yY4vj4GoA5t4pJuSCH%2Fdesign-loyalty-card-apple-example-loyalty-card-2.png?alt=media&#x26;token=983317c6-bc3d-4abc-a0ff-822e167d5425</a></td></tr><tr><td align="center">Apple pass</td><td data-object-fit="contain" data-alt="Apple example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FdYTfGor2yipBBTxLLxq6%2Fdesign-loyalty-card-apple-example-loyalty-card.png?alt=media&#x26;token=072864e6-5b62-47fa-ac7a-dfcf616e9f78">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FdYTfGor2yipBBTxLLxq6%2Fdesign-loyalty-card-apple-example-loyalty-card.png?alt=media&#x26;token=072864e6-5b62-47fa-ac7a-dfcf616e9f78</a></td></tr></tbody></table>

<table data-view="cards"><thead><tr><th align="center"></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td align="center">Google pass</td><td data-object-fit="contain" data-alt="Google example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F9lLIIOnTwgCm0tELCNvQ%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26.png?alt=media&#x26;token=5157706d-fae2-43a8-8290-e52dc5fb6012">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F9lLIIOnTwgCm0tELCNvQ%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26.png?alt=media&#x26;token=5157706d-fae2-43a8-8290-e52dc5fb6012</a></td></tr><tr><td align="center">Google pass</td><td data-object-fit="contain" data-alt="Google example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F532V5smCuiYijIi1jcby%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26-3.png?alt=media&#x26;token=23ab6e7e-c8bb-4d11-b3f3-f810d0cdbaef">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2F532V5smCuiYijIi1jcby%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26-3.png?alt=media&#x26;token=23ab6e7e-c8bb-4d11-b3f3-f810d0cdbaef</a></td></tr><tr><td align="center">Google pass</td><td data-object-fit="contain" data-alt="Google example loyalty card"><a href="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FgV44BJ5SHBMyyecGBbZR%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26-2.png?alt=media&#x26;token=4d8e95ed-8ad7-4eb2-a505-1d8c7914eebc">https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2FgV44BJ5SHBMyyecGBbZR%2Fdesign-loyalty-card-capture-d-e-cran-2026-01-26-2.png?alt=media&#x26;token=4d8e95ed-8ad7-4eb2-a505-1d8c7914eebc</a></td></tr></tbody></table>

Reference documentation: [Apple Wallet passes](https://developer.apple.com/documentation/walletpasses) and the [Google Wallet loyalty template](https://developers.google.com/wallet/retail/loyalty-cards/resources/template).

## What is specific to a loyalty card

* **Barcode.** The barcode value is the identifier that the point-of-sale terminal uses to find the member. Choose a barcode type that the terminals read on a phone screen. See the Barcode section of the [Apple tab](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md) and of the [Google tab](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/google-tab.md).
* **Back fields (Apple) and messages (Google).** Use them for how the program works, the available rewards, receipts and links such as the favorite store, the account page or the terms and conditions.
* **Tier and points as metadata.** Store the tier or the points as [metadata](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/general-tab.md#metadata) to filter passes in the pass list and to target them with an [automation](https://docs.thewalletcrew.io/guides-animation/engage-and-animate/automatisation.md).

### On Apple Wallet

* **Points in the header.** Put the points balance, or the status, in the header fields, the only ones visible when passes are stacked.
* **Locations, beacons and NFC.** See [Locations and beacons](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#locations-and-beacons) and [NFC](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#nfc) in the Apple tab. The locations are also in the Google tab.

### On Google Wallet

* **Google loyalty fields.** The loyalty settings are listed in [Customer card and Stamp card (Loyalty)](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/google-tab.md#customer-card-and-stamp-card-loyalty). A **Program logo** is required: Google refuses the template without it. Google places each value according to its field, so keep the points in the points field, not the member name. Put dynamic values (for example `{{ firstName }}`) in dedicated dynamic fields, not in label fields.

## Poster layout on iOS 27

iOS 27 gives Apple Wallet a new image-led design for loyalty cards, the **poster layout**. A full-card artwork replaces the strip image, a dedicated logo sits at the top, the main information is laid over the image and up to two **featured actions** appear under the pass. The Wallet Crew builds the poster and the classic version of the pass from the same template: iPhones on iOS 27 and later show the poster, older iPhones keep the classic layout. Existing passes do not change until the template uses the poster layout and the passes are refreshed. The settings are described in [Pass style and layout](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#pass-style-and-layout).

### Turn the poster options on

1. Go to **Wallet → Templates**, open the loyalty template, then the **Apple** tab.
2. In the **General** section, tick **Use new poster layout** (marked **iOS 27+**). The settings that only the poster uses are marked **Poster - iOS 27+**. The iOS 27 preview and the new fields appear.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-68e1e95c9f357fcecedb88ef2b4a5deacf5624ec%2Floyalty-card-poster-layout-option.png?alt=media" alt="General section of the Apple tab with the Use new poster layout option"><figcaption><p>The poster layout option is in the General section of the Apple tab.</p></figcaption></figure>

{% hint style="warning" %}
**Keep the classic content.** The strip image, the logo and the primary field are still used by iPhones on iOS 26 and earlier. Do not empty them when moving to the poster layout. The secondary fields feed the classic layout and the summary fields feed the poster: a value left empty on one side is missing on the matching iPhones.
{% endhint %}

### Poster images

The poster layout adds two image positions in the **Images** section, both marked **iOS 27+**. The editor shows the space Apple Wallet allots under each image.

| Position                        | Size                                                   | Tips                                                                                                                                                                                                  |
| ------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Artwork (poster background)** | 1236 × 1680 px (the card is 358 × 503 to 400 × 560 pt) | Full-card background. Keep the subject in the center, as iOS crops the edges differently on each iPhone. Avoid text inside the image, and keep a calm, contrasted area at the bottom for the barcode. |
| **Logo (poster layout)**        | 378 × 108 px (126 × 36 pt)                             | Top left of the poster, in place of the standard logo. A transparent PNG in one color, contrasting with the artwork, reads best.                                                                      |

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-d46b2a41cfd8fcf6c044401c4d8ed4facaf7ecb6%2Floyalty-card-poster-images.png?alt=media" alt="Images section of the Apple tab with the poster artwork and poster logo positions"><figcaption><p>The Images section shows the allotted space under each poster image.</p></figcaption></figure>

The classic images stay in the template for older iPhones: the **icon** (87 × 87 px, required), the **logo** (fits 858 × 150 px; upload it 150 px high) and the **strip** (1200 × 462 px). The **Edit image** option reframes the artwork without uploading a new file.

<figure><img src="https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FALma4tz8O9tZk53CoDMw%2F07-apple-primary-logo.png?alt=media&#x26;token=441f9cdc-d29f-4c53-b800-c8ba1cc902b9" alt="Apple Wallet poster layout with the primary logo in the top-left highlighted"><figcaption><p>The poster logo. Check that it stays readable against the top of the artwork.</p></figcaption></figure>

### Summary and footer fields

The poster does not display the primary field. Its main information comes from the **summary fields**, shown below the barcode, and from one **footer field** at the bottom of the card. The header fields keep their role. See [Fields](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#fields) for the sections.

What is specific to a loyalty card:

* The poster displays only the first summary fields, so put the most important first. The member name, tier, points balance or card number are typical content.
* The footer holds one field, with a value and no label. Use it for one short piece of information such as the program name.

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-97eb2c6e6b1844db888200a1058b35aa776e7503%2Floyalty-card-poster-summary-fields.png?alt=media" alt="Front fields section of the Apple tab with the summary fields of the poster layout"><figcaption><p>Summary fields sit in the Front fields section, under Primary Fields.</p></figcaption></figure>

### Featured actions for a loyalty card

Featured actions are buttons displayed directly under the pass on iOS 27, at most two, in the order of the list. iPhones on iOS 26 and earlier do not show them: keep the key link in the back fields too. They shorten the path to the most useful action of the programme. The most relevant types for a loyalty card are **View membership benefits**, **View Offers & Rewards**, **Shop online or in-app**, **Order delivery or pickup** and **Book an appointment**. The full list of types and the URL options are in [Featured actions](https://docs.thewalletcrew.io/configure/advanced-configuration/wallet/template-configuration/apple-tab.md#featured-actions). When **Enable link tracking** is on, taps are tracked like other pass links, with the origin (back of the card or featured actions).

<figure><img src="https://493872178-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F96iMF0cPuLTC7ZRnUWG9%2Fuploads%2Fgit-blob-7c9231a72c9adcb64d2f13143c92aef0e4e76097%2Floyalty-card-featured-actions.png?alt=media" alt="Featured actions section of the Apple tab with two actions"><figcaption><p>The Featured actions section sits at the bottom of the Apple tab.</p></figcaption></figure>

### Test before rolling out

The preview in the admin console is a close approximation, but Apple Wallet controls the final cropping and rendering. Before pushing the new design to existing passes:

1. Install a test pass on an iPhone on iOS 27 and on an iPhone on iOS 26 or earlier.
2. Check the artwork cropping and the readability of every field.
3. Scan the barcode at the till.
4. Tap each featured action.

For large volumes, schedule the push outside peak hours.

## FAQ

<details>

<summary><strong>What do holders on iOS 26 or earlier see?</strong></summary>

The classic layout, built from the same template with the logo, strip, primary field and back fields. The footer and the featured actions are not displayed, while the barcode, updates and notifications work as usual. Google Wallet is not affected: the Google tab is independent.

</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-design/design/loyalty-card-template-configuration.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.
