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.

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.

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.

Apple Wallet

Every position can carry a different picture per language.

Where it lands	Position	Size	What it is
	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 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.
	Artwork	1074 × 1344 px	Poster event tickets from iOS 18, poster generic passes from iOS 27.
	Background	540 × 660 px	Event tickets only, and only when the ticket has no strip.
	Thumbnail	270 × 270 px	Generic passes, and event tickets without a strip.
	Logo	480 × 150 px (maximum)	Top left of every style, next to the pass name. A transparent PNG lets the card colour show through.
	Icon	87 × 87 px	Notifications, lock screen and passes sent by email. It never appears on the card itself.
	Primary logo	378 × 90 px	The logo of the poster layouts, which carry their own instead of the standard one.
	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
	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.
	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 %.
	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.
	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 %.
	Wide program logo	1280 × 400 px	Used in place of the program logo in the card header.
	Title image	660 × 660 px	The title image of an offer, shown in both the list and the detail view. It applies to offers.
	Wide title image	1280 × 400 px	Used in place of the title image in the card header.

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.

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	—	—	—

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.

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.

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.

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.
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 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. Each position states its size and the pass types it applies to; positions already in the theme are marked Added.

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.

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.

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 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.

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.

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 carries at most one theme. It is set from the Theme field on the pass, or from Actions → Apply a theme.

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.

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

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. 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 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.

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.