> 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/configure/advanced-configuration/wallet/wallet-pass-themes.md). # Wallet pass themes Create reusable Apple Wallet and Google Wallet pass themes. Apply campaign colours, images and translations without changing the pass template. A wallet pass theme is a reusable visual layer for Apple Wallet and Google Wallet passes. It applies campaign colours, images, and optional text. It does not change pass fields, barcodes, or templates. Use themes for seasonal campaigns, co-branding, and programme variants. A single theme can apply to many passes. Updating the theme updates its shared design. ## Wallet pass themes: what they are and when to use them A theme is a named set of colours, images, and optional translated content. It gives a season, campaign, or partnership a consistent visual identity. A theme sits on top of a pass template. The template controls fields, barcodes, and pass structure. The theme controls the visual identity. This separation avoids duplicating templates for every campaign.
Real-world examples * A fashion retailer dresses its loyalty cards in the summer collection artwork in June, and in the winter one in November, while the card itself never changes. * A show organiser gives every ticket for one tour the visual identity of that tour, on top of the ticket template used for all shows. * A brand running a three-month partnership applies a co-branded theme to the passes of the customers concerned, then clears it when the partnership ends. * A staff card or a VIP card is kept deliberately distinct from the rest of the programme with its own theme.
### How themes work Four rules explain theme behaviour: 1. A pass has **one theme or none**. Themes do not stack. 2. Passes reference a theme. They do not copy its settings. Changes appear when passes refresh. 3. A theme changes appearance only. Validity, stock, and redemption belong to an offer. 4. Empty settings inherit from the template. This includes colours and image positions. ## What a wallet pass theme changes A theme can set images, colours, and optional text. Images have the greatest visual impact. | What | Details | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Default image** | A seasonal banner for both platforms. It fills two positions only, the Apple strip and the Google hero, and only when the theme has no override of its own for them. The strip is shorter on event tickets than on other passes, and one default image serves every pass kind, so everything important belongs in the middle of the image. | | **Image overrides** | Replace logos, icons, thumbnails, or backgrounds individually. Each override is intentional. Every position the theme does not override keeps the pass template's image. | | **Colours** | Set the card background, field values, and field labels. Label colour applies to Apple Wallet only. Colours do not vary by language. | | **Title and description** | Add two short, translatable texts. The template must be configured to display them. Otherwise, they do not appear on the pass. Whether they follow the device language depends on how the template places them, as explained in [Languages](#languages). | ### What a theme never changes Themes do not change fields, field layout, barcodes, links, back-of-pass content, or pass behaviour. Those settings remain in the template. A re-themed pass has new artwork on the same card. ### Languages Apple Wallet supports language-specific images. Google Wallet stores one image per position and always uses the default language. Theme titles and descriptions follow a different rule, because the pass template decides how they are rendered. `{{ theme.title }}` and `{{ theme.description }}` follow the device language only when they are placed in the template's translated values, the per-language values of a field. A template field written once is rendered once, in a single language, whatever translations the theme carries. A theme translated into French therefore shows its French title on a French device only when the template field that displays it has per-language values. ## Wallet pass images a theme can replace The default image supplies the main banner on both platforms: the Apple strip and the Google hero, unless the theme overrides either of them. Other images are replaced by position because Apple Wallet and Google Wallet use different layouts. Fifteen positions are available. A position the theme does not override keeps its template image. In the two tables below, the diagram shows where the position lands on the card, with the replaced area highlighted. {% hint style="info" %} **Why only two positions use the default image.** The Apple strip and Google hero are both wide banners. Logos, icons, and backgrounds need different proportions. Each of those positions needs its own file. {% endhint %} ### Apple Wallet Every position can carry a different picture per language. | Where it lands | Position | Size | What it is | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ![Apple Wallet card with the strip area behind the fields highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2Fce7SV9RiYJCHAsAxZ2e7%2F01-apple-strip.png?alt=media\&token=74468e78-ad43-4fa8-a5ce-f05abc5f9c0a) | **Strip** | 1125 × 294 px on event tickets, 1125 × 432 px on gift cards and offers, 1125 × 369 px on loyalty and stamp cards. These are [Apple's sizes](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/Creating.html) at @3x. | Not shown on generic passes or poster layouts. On an event ticket, a strip hides the background and the thumbnail. Uses the default image unless the theme overrides it. | | ![Apple Wallet poster layout with the full-card artwork highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2Fy36POriDHQhqvbP69IlE%2F02-apple-artwork.png?alt=media\&token=15fa0108-9873-4f00-9ea7-b6a2a7d2b5c7) | **Artwork** | 1074 × 1344 px | Poster event tickets from iOS 18, poster generic passes from iOS 27. | | ![Apple Wallet event ticket with the whole card background highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FUbU5QOgSoGEpVarYP7fd%2F03-apple-background.png?alt=media\&token=f2061595-2bea-4884-87bd-ef00b619fe1f) | **Background** | 540 × 660 px | Event tickets only, and only when the ticket has no strip. | | ![Apple Wallet card with the square thumbnail beside the fields highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2F6FyAZFij27w37zAtyOMN%2F04-apple-thumbnail.png?alt=media\&token=1e921273-3137-4041-98fd-ffc119d76f71) | **Thumbnail** | 270 × 270 px | Generic passes, and event tickets without a strip. | | ![Apple Wallet card with the logo in the top-left corner highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2F0Oqe2pORMjsZrwyswe8A%2F05-apple-logo.png?alt=media\&token=44ad1bc7-9cd8-4f9c-b0eb-4f3fe419a9e9) | **Logo** | 480 × 150 px (maximum) | Top left of every style, next to the pass name. A transparent PNG lets the card colour show through. | | ![An iOS notification with the small square pass icon highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2Fh4f42sSgfx2PVZI5Qwju%2F06-apple-icon.png?alt=media\&token=349ea01b-169e-4d9d-b46d-9ea310284474) | **Icon** | 87 × 87 px | Notifications, lock screen and passes sent by email. It never appears on the card itself. | | ![Apple Wallet poster layout with the primary logo in the top-left highlighted](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\&token=441f9cdc-d29f-4c53-b800-c8ba1cc902b9) | **Primary logo** | 378 × 90 px | The logo of the poster layouts, which carry their own instead of the standard one. | | ![Apple Wallet poster layout with the secondary logo in the footer highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FavRKuveL649emKmbktgH%2F08-apple-secondary-logo.png?alt=media\&token=8b3b6976-10b9-4d42-9375-506ce35a3014) | **Secondary logo** | 405 × 36 px | A second, wider mark inset in the poster footer — usually a venue or a partner. | ### Google Wallet One picture per position, always the default language. | Where it lands | Position | Size | What it is | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![Google Wallet card with the wide hero banner highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FmTQ7z07NAg3SKJTVzzZP%2F09-google-hero.png?alt=media\&token=460864c8-fbfa-41a8-8875-904188a00913) | **Hero** | 1032 × 336 px | The wide banner across the front of the card, on loyalty, event ticket, gift card and offer passes. The most visible image a theme can set on Google Wallet. Uses the default image unless the theme overrides it. | | ![Google Wallet card with the square logo in the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FHFInfflMnb1wgTR183AJ%2F10-google-logo.png?alt=media\&token=4be23a70-3e78-40b0-a74a-e0a2f97b46ac) | **Logo** | 660 × 660 px | The square logo in the top-left of the card, beside the brand name. It applies to event tickets and generic passes. Google crops it to a circle, so keep the content inside the inner 70 %. | | ![Google Wallet card with the wide logo across the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FgacAmRgzk8IzRaieuw2f%2F11-google-wide-logo.png?alt=media\&token=d422d986-5a62-4dda-93f1-7306bf384d70) | **Wide logo** | 1280 × 400 px | Used in place of the logo in the card header, when the brand mark reads better wide than square. It applies to event tickets and generic passes. | | ![Google Wallet card with the program logo in the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FeFsvFw4i45zsLjpmTRHQ%2F12-google-program-logo.png?alt=media\&token=cfb3f8f4-b976-4ca1-8ffc-fc86c712f0e3) | **Program logo** | 660 × 660 px | The logo of the loyalty programme or the gift card, shown in both the list and the detail view. It applies to loyalty, stamp cards, and gift cards. Google crops it to a circle, so keep the content inside the inner 70 %. | | ![Google Wallet card with the wide program logo across the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2Fc0VnNYzozIxXGtcagw8B%2F13-google-wide-program-logo.png?alt=media\&token=5be033d2-4d57-467c-abf8-d56fd6e803dd) | **Wide program logo** | 1280 × 400 px | Used in place of the program logo in the card header. | | ![Google Wallet offer card with the title image in the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FiPUf4bUgx2D1WfcDQaVc%2F14-google-title-image.png?alt=media\&token=b3f76556-3f57-4761-9f74-ccec6d89f542) | **Title image** | 660 × 660 px | The title image of an offer, shown in both the list and the detail view. It applies to offers. | | ![Google Wallet offer card with the wide title image across the header highlighted](https://123508161-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FDJrf9G0l7ArnvuwEH0a8%2Fuploads%2FwUz7eupJ4TDJkJBEPJ5S%2F15-google-wide-title-image.png?alt=media\&token=f7f664df-5f2e-4f55-bda4-9a5dd770580e) | **Wide title image** | 1280 × 400 px | Used in place of the title image in the card header. | {% hint style="info" %} **A square logo override hides the template's wide version.** Google Wallet shows the wide version of a logo whenever both a square and a wide version exist. A theme that overrides only a square logo — the logo, the program logo or the title image — would otherwise stay hidden behind the template's wide version. For that reason, the template's wide version of that logo is not shown on passes wearing such a theme, and the theme's square logo appears instead. {% endhint %} Sizes are the largest dimensions each platform renders. Larger files are scaled down. Images are bundled into the pass exactly as they are stored in the theme, with no format conversion; only the strip and the hero may be cropped, as described below. Use transparent PNG files for logos so the card colour remains visible. ### How the strip and the hero are cropped Whether the default image is cropped depends on the pass template, not on the theme. When the template has image optimisation turned on, the image is cropped to the exact Apple strip and Google hero sizes. Without it, the image is shipped as uploaded and Apple Wallet or Google Wallet fits it into the space available. In both cases, one default image serves every pass kind, and the strip is shorter on event tickets than on other passes. Artwork with its subject in the middle and plain edges reads well whichever way it ends up framed. ### Which positions apply to which pass This matrix shows which image positions each pass kind uses. A position not shown here does not appear on that pass. | Position | Loyalty | Stamp card | Gift card | Offer | Event ticket | Generic | Poster | | --------------------------- | ------- | ---------- | --------- | ----- | ------------------------------------ | ------- | ------ | | Apple strip / default image | Yes | Yes | Yes | Yes | Yes — hides background and thumbnail | No | No | | Apple background | — | — | — | — | Yes | — | — | | Apple thumbnail | — | — | — | — | Yes, without strip | Yes | — | | Apple artwork | — | — | — | — | — | — | Yes | | Apple primary logo | — | — | — | — | — | — | Yes | | Apple secondary logo | — | — | — | — | — | — | Yes | | Google hero | Yes | Yes | Yes | Yes | Yes | Yes | Yes | | Google logo | — | — | — | — | Yes | Yes | — | | Google program logo | Yes | Yes | Yes | — | — | — | — | | Google title image | — | — | — | Yes | — | — | — | {% hint style="warning" %} A theme applied to passes of several kinds should carry the logo, program logo and title image positions, otherwise the logo changes on some passes only. {% endhint %} ## Create a wallet pass theme Themes live under **Wallet → Themes**. Search by name and switch between card and table views. Both views show the same themes. Card view shows the default image, colours, name, and identifier. It is best for choosing a theme visually.
The theme list in card view: each theme is a tile showing its artwork, its colours, its name and its identifier.

Card view. Check that each tile shows the artwork expected for the campaign — a theme is recognised here by its image rather than by its name.

Table view lists each theme as a row. Use it to check usage, recent changes, and translations. Columns can be sorted, filtered, and hidden.
The theme list in table view, with columns for tags, colours, slots, languages, passes, created and modified.

Table view. The Passes column is the one to read before editing or deleting a theme: it says how many cards are affected.

| Column | What it shows | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Identifier | The fixed reference used by passes, automations, and external systems. It is generated when the theme is created and never changes. | | Tags | Free-text labels used to search and filter themes. Use consistent labels for seasons, campaigns, and programmes. | | Colours | Theme colour swatches. An empty value inherits the template colour. | | Slots | The number of image overrides. `0` means all images come from the template, except the Apple strip and the Google hero, which take the default image. | | Languages | Languages with translated text or images. `—` means default language only. | | Passes | The number of passes using the theme. A theme that passes carry cannot be deleted; see [Delete a wallet pass theme](#delete-a-wallet-pass-theme). | | Created / Modified | Creation date and most recent save. A recently modified live theme may have changed pass appearance. | The **…** menu in each row or card provides three actions: edit the theme, list assigned passes, or delete it. Deletion is unavailable while passes carry the theme or an enabled automation applies it. ### Making one Create the images first. Then add colours and optional content. This order makes design validation faster. 1. Go to **Wallet → Themes** and select **Create a theme**. 2. **Name it.** The campaign name works well — *Summer 2026*, *Black Friday*. The name is what everyone sees in the theme picker later, and the identifier is derived from it at creation and never changes, so the real name is worth settling now. 3. **Add tags.** Tags make themes easier to find later. Use consistent, short labels such as *seasonal*, *summer-2026*, and *loyalty*. 4. **Add the default image.** This is the banner that covers the Apple strip and the Google hero, unless an override replaces either of them. Design at 1125 × 432 px, keep the subject in the middle and leave the edges plain: the strip is shorter on event tickets than on other passes, and fields sit on top of it. 5. **Add template overrides** for anything the default image does not cover: select **Add an override**, pick the position, upload the file, and repeat for each one. 6. **Set the colours.** Background, foreground, and label colour for Apple Wallet. Any of them left empty keeps the template's. 7. **Write the content**, if the theme has a title or a description to show. The language selector in the card header adds translations. 8. **Save.** On a theme no pass is using yet, that is the end of it. On one that passes are already wearing, saving asks a question first.
The theme editor: default image and colours on the first row, content and template overrides below.

The editor. The header counts the passes wearing the theme and says when they will pick a change up — check it before saving.

The override picker: every position shows its size, which pass types it applies to, and a diagram of where it lands on the card.

The override picker. Each position states its size and the pass types it applies to; positions already in the theme are marked Added.

Four positions replaced in the theme: Apple logo, thumbnail and icon, plus the Google program logo.

Four positions replaced — Apple logo, thumbnail and icon, plus the Google program logo. Verify that every position a campaign depends on appears here; anything absent still comes from the template or from the default image.

{% hint style="warning" %} **There is no draft state.** A theme goes live the moment it is saved. Trying a design safely means creating a second theme and moving one test pass onto it. {% endhint %} ### Saving a theme that passes are already using Editing a theme changes its shared design. Existing wallet passes keep their current version until they refresh. The save dialog controls whether that refresh happens immediately. When no pass uses the theme, saving only stores the changes. When passes use it, the **Save theme** dialog shows the affected pass count. It also offers to refresh those passes in the same action.
The Save theme dialog, stating how many passes use the theme, with the push option switched on.

The save dialog. Read the pass count, then decide: left off, the theme is saved and the passes are left to refresh on their own.

With the switch off, **Save** updates the theme only. Each pass receives the new design during its next refresh. Use this option for small changes or pre-launch preparation. With the switch on, **Save & push update** saves the theme and refreshes every assigned pass. The dialog shows an estimated duration. **Advanced Settings** controls refresh speed and metadata refresh. Use this option when the artwork must be live immediately. **Cancel** discards the changes. The theme saves before the refresh starts. If the refresh fails, the theme remains saved. Save again with the switch on, or use an automation, to retry. ### Practical limits Theme images must be PNG or JPEG, because they are bundled into the pass exactly as stored. An upload in any other format, such as WebP, GIF or SVG, is refused. When an image is picked in the back office, it is converted to PNG at the moment it is cropped. Images are accepted up to **8 MB** each, with transparent PNG the right format for logos. A theme carries up to **20 tags**, and one image per position — there is no second Apple logo. {% hint style="warning" %} **Images given as a URL are not checked.** The format check applies to uploaded files only. An image referenced by an external URL instead of being uploaded is not format-checked, so it must already be a PNG or JPEG file. {% endhint %} ## Apply a theme to wallet passes A theme does nothing until passes point at it. Three routes do that: one pass at a time in the back office, a whole audience through an automation, or an external system through the API. ### To one pass, from the back office Use this route when one pass needs a different design. It affects that pass only.
Real-world examples * **Trying a design before a campaign.** The new theme is put on a test pass and opened on a real phone, on both Apple Wallet and Google Wallet, before an automation puts it in front of an audience. * **Fixing one customer.** A pass that an automation missed, or one a customer service agent can see is still on last season's artwork. * **A deliberate exception.** A staff card, a VIP or a partner pass that should not look like everyone else's.
1. Open the pass: **Wallet → Passes**, then the pass concerned. 2. Select **Actions → Apply a theme**. 3. Pick a theme from the grid. The dialog opens on the theme the pass is wearing today, which makes the starting point visible. 4. Confirm. Taking the theme off instead means choosing **None — use the pass type as configured** and confirming with **Remove the theme**.
A pass detail page showing the Theme field and the Actions menu with Apply a theme.

A pass carries at most one theme. It is set from the Theme field on the pass, or from Actions → Apply a theme.

The theme picker on a pass, showing each theme's artwork and colours.

The picker shows each theme's artwork and colours, so the choice is made on the design rather than on the name.

The change applies immediately. The pass refreshes so the new artwork reaches the device. ### To many passes, with an automation Use an automation to run a campaign at scale. It selects an audience and applies a theme based on a date, schedule, or pass event. 1. Go to **Engagement → Automations** and create one. 2. Set the **trigger**: a launch date, a recurrence, a pass event, or a date relative to a field on the pass. 3. Set the **audience** with filters — a pass type, a tier, a store. With no filter, every pass of the brand is concerned. 4. Select **Add an action → Apply a theme** and pick the theme. Stripping the theme instead means switching on **Remove the theme instead**. 5. Set the **end condition**, then save and switch the automation on.
The Add an action menu in an automation, with Apply a theme among the available actions.

Applying a theme is one of the actions an automation can perform on a pass.

An automation with an Apply a theme step, the audience above it and the theme picker on the right.

The theme step in an automation chain. Confirm the audience above the step before switching the automation on; Remove the theme instead turns the same step into a clean-up.

An automation can combine several actions. It can apply an offer, update pass data, change a template, apply a theme, and send a notification. The platform pushes the pass once after all actions run. The refresh is silent. Add a **Send a notification** action when an end-user must be alerted. Applying a theme leaves pass fields and structure unchanged. ### From external systems A CRM, e-commerce platform, or other integration can create a pass with a theme. It can also assign a different theme later. Set the theme field to a theme identifier to apply it. Omit the field to keep the current theme. Send an empty value to remove it. Two rules matter when an integration also manages the themes themselves. A theme identifier never changes, because passes and automations reference it: updating a theme with a body `id` different from the `id` in the URL is refused with `400`. And every error from the theme endpoints, like the error the pass endpoints return for an unknown `themeId`, is returned as problem details (`application/problem+json`). Validation errors name the offending field, such as `id`, `file` or `themeId`, so the integration can report which value to fix. Endpoints, payloads, and permissions are available in the [API reference](https://docs.thewalletcrew.io/api-reference/). For audience-wide changes, an automation usually requires less integration work. ## Delete a wallet pass theme Deleting a theme is blocked while something still depends on it, so that no pass and no running automation is left pointing at a theme that has gone. A theme cannot be deleted while a pass carries it, or while an enabled automation applies it. A disabled automation does not block the deletion. When deletion is blocked, the back office says why — the number of passes carrying the theme and the names of the automations applying it — and the delete action is disabled. Unblocking it takes two steps: 1. Move the passes to another theme, or remove their theme, one pass at a time from the pass page or for an audience with an automation. 2. Disable the automations listed, or change the theme they apply. Once neither passes nor enabled automations depend on the theme, the delete action in the **…** menu becomes available again. Deleting a theme also deletes its images, so keep source files outside The Wallet Crew. A pass with a missing theme falls back to its template and is marked as *missing* on the pass page. ## Theme events and pass updates Theme catalogue changes can notify connected webhooks, marketing tools, and back-office systems. These events provide an audit trail and let other systems react automatically. ### The three theme events | Event | Sent when | What it carries | | ------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | Theme created (`Theme:Created`) | A theme is added. | Which theme — identifier, name and tags — and who added it. | | Theme updated (`Theme:Updated`) | An existing theme is saved. | Which theme — identifier, name and tags — and who saved it. It does not say which parts of the theme changed. | | Theme deleted (`Theme:Deleted`) | A theme is removed. | The theme's identity — identifier, name and tags — as it was before deletion, and who removed it. Its colours and images are not included. | Each theme event carries a `theme` object (`themeId`, `name`, `tags`) and a `user` object (`credentialType`, `id`, `name`) that says who made the change. `credentialType` is `User` for a signed-in back-office user, `ApiKey` for an API key, or `Unknown` when the change happened outside a request and carries no identity. For a `User`, `id` is the user identifier at the identity provider; for an `ApiKey`, it is `apiKey:{name}` and `name` is the name the key was issued under; for `Unknown`, `id` can be empty. The events carry no email address: the [users API](/api-reference/advanced/users.md) resolves a user identifier to a person. This identity matches the configuration history. ### When a pass moves onto a theme Theme events describe catalogue changes. Pass events describe changes to an individual pass. | Event | Sent when | What it carries | | ------------------------------------------------------------ | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Pass theme changed (`Pass:ThemeChanged`) | A pass is moved onto a different theme, or has its theme taken away. | The pass, the theme it carries now, and the theme it carried before. Either can be empty — empty before means it had none, empty after means the theme was removed. | | Pass created / Pass updated (`Pass:Created`, `Pass:Updated`) | Every creation and every update, theme or not. | The theme the pass carries, alongside its template and identifiers. | *Pass updated* reports the pass's current state. *Pass theme changed* records the move and both theme values. Use the latter to measure campaign assignment without comparing pass histories. *Pass theme changed* is sent only when the assigned theme differs. Re-saving the same theme sends no event. Creating a pass with a theme sends *Pass created*, not *Pass theme changed*. The same behaviour applies to back-office, automation, and API changes. Like every pass event, *Pass theme changed* carries no actor: neither a user nor an API key. The event says what moved, not who moved it.
Real-world examples * Keeping a record of who edited a seasonal theme, and on what date. * Alerting a channel when a live theme is edited, since every pass carrying it is about to change. * Measuring how a campaign rolled out, by counting the passes that moved onto its theme. * Letting a downstream system know a campaign skin has gone out, without polling for it.
## Launch checklist for a wallet pass theme A theme becomes live when it is saved. It does not revert automatically. Review the following points before launch: * **Plan the end date.** Create a second automation to apply the next theme or remove the current one. * **Check both platforms.** Apple Wallet and Google Wallet use different image positions. * **Check the languages.** When the theme has a translated title or description, confirm that the template displays it through per-language values; otherwise one language shows everywhere. * **Test one pass first.** Install a test pass, apply the theme, and review it on each device type. A theme still carried by passes, or applied by an enabled automation, cannot be deleted. The steps to free it are in [Delete a wallet pass theme](#delete-a-wallet-pass-theme). ## FAQ
When is a theme the right tool rather than a change to the template? Use a theme when only the visual design changes: colours, images, or a seasonal title. Change the template when the pass itself changes, such as its fields, barcode, or structure.
What is the difference between a theme and an offer? An offer gives end-users something to use. It can include validity dates, stock, and redemption. A theme changes only appearance. An automation can apply an offer and a theme together.
Can one pass wear two themes? No. A pass wears one theme, or none. Themes do not stack.
When do end-users actually see the new look? End-users see the change when their pass refreshes. Applying a theme directly or through an automation refreshes the pass immediately. Editing a theme refreshes assigned passes only when **Push the update to these passes as well** is enabled during saving. Otherwise, each pass waits for its next refresh. Refreshes are silent. Add a **Send a notification** step to alert end-users.
How is the previous look put back? Nothing reverts automatically. Apply the next theme or remove the current one. Use the pass page for one pass, or an automation for an audience.
Can a theme be tried without touching live passes? Yes. Creating a theme changes no passes. Apply it to one test pass and review it on a physical device before wider rollout.
Which image format should be used for a wallet pass theme? PNG or JPEG, up to 8 MB. Other formats, such as WebP, GIF or SVG, are refused, because images are bundled into the pass exactly as stored. An image given as an external URL is not checked, so it must already be PNG or JPEG. Use transparent PNG files for logos, and artwork at the listed size or larger.
Why is the theme title shown in one language only? The template decides. `{{ theme.title }}` and `{{ theme.description }}` follow the device language only when the template places them in its translated values, the per-language values of a field. A field written once is rendered once, in a single language. Move the placeholder into the field's per-language values, then refresh a test pass on a device set to each language.
Do Apple Wallet and Google Wallet show the same theme images? No. The default image becomes the Apple Wallet strip and the Google Wallet hero, unless the theme overrides either position. Other positions differ by platform and keep the template's image unless overridden. Apple Wallet supports language-specific images. Google Wallet uses the default-language image.
Why does the default image look cropped differently on two passes? The strip is shorter on event tickets than on other passes, and one default image serves every pass kind. When the template has image optimisation turned on, the image is cropped to the exact strip and hero sizes; without it, the wallet fits the image as uploaded. Keeping the subject in the middle of the image avoids losing it on either kind.
Can an active theme be deleted? No. A theme cannot be deleted while a pass carries it or an enabled automation applies it; a disabled automation does not block it. The back office lists the pass count and the automations concerned. Move the passes to another theme or remove their theme, then disable those automations or change the theme they apply. Keep source image files outside The Wallet Crew because deletion removes theme images.
--- # 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/configure/advanced-configuration/wallet/wallet-pass-themes.md?ask=&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.