# Apple Wallet Templates (/docs/apple-wallet-templates)



Templates control the colours, text and images on your Apple Wallet passes.
Use the [pass designer](/dashboard/templates) for a live preview, or create a template through the API.

## Create a template [#create-a-template]

```ts
const { data: template, error } = await eventlayer.appleWalletTemplates.create({
  backgroundColor: "rgb(60, 60, 60)",
  foregroundColor: "rgb(255, 255, 255)",
  logoText: "After Hours",
});
if (error) throw error;
```

## Apply it to an event [#apply-it-to-an-event]

```ts
const { error } = await eventlayer.events.update({
  eventId: "ev_123",
  appleWalletTemplateId: template.id,
});
if (error) throw error;
```

Now [generate a Wallet pass](/docs/guides/apple-wallet) for an assigned ticket.

## Override it for a ticket type [#override-it-for-a-ticket-type]

Assign `appleWalletTemplateId` with `eventlayer.ticketTypes.update()`
to give a type its own design. Ticket-type fields take precedence; null fields
fall back to the event template. Set an assignment to `null` to remove it.

## Upload an image [#upload-an-image]

Pass your uploaded file to the SDK:

```ts
const { error } = await eventlayer.appleWalletTemplates.uploadImage({
  templateId: "awt_123",
  imageType: "hero",
  file,
  contentType: "image/png",
});
if (error) throw error;
```

## Template properties [#template-properties]

| Property              | Type              | Description                                                                                      |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------ |
| `background_color`    | `string \| null`  | Background color in CSS format (e.g. `rgb(60, 60, 60)`).                                         |
| `foreground_color`    | `string \| null`  | Text color in CSS format (e.g. `rgb(255, 255, 255)`).                                            |
| `label_color`         | `string \| null`  | Label color in CSS format (e.g. `rgb(200, 200, 200)`).                                           |
| `logo_text`           | `string \| null`  | Text displayed next to the pass logo.                                                            |
| `header_text`         | `string \| null`  | Text displayed in the header row of the pass.                                                    |
| `fine_print`          | `string \| null`  | Fine print text shown on the back of the pass.                                                   |
| `sharing_prohibited`  | `boolean \| null` | Prevents sharing the pass via Wallet's sharing feature.                                          |
| `grouping_identifier` | `string \| null`  | Groups related passes together in Wallet.                                                        |
| `show_barcode`        | `boolean \| null` | Whether the QR code barcode is shown on the pass. Defaults to `true`. Set to `false` to hide it. |

The template values are written into the pass JSON during generation.

Apple requires `appLaunchURL` to be paired with an associated App Store app.
Contact Eventlayer support to enable this integration for your account. If it
is not enabled, Eventlayer safely omits `appLaunchURL` from the pass.

The response also includes `hero_image_url`, `logo_image_url`, and `background_image_url`. These are read-only: they are set by the image upload endpoint below, not via `create` or `update`.

## Image types [#image-types]

Images are uploaded as `multipart/form-data` to `POST /v1/apple-wallet-templates/{id}/images` (fields: `image_type` and `file`). Uploads are validated before storage: formats PNG, JPEG, or WebP, max 10MB, and within the maximum dimensions for the slot.

| Image Type   | Pass File        | Purpose                                     | Max Dimensions |
| ------------ | ---------------- | ------------------------------------------- | -------------- |
| `hero`       | `strip.png`      | Hero image displayed on the pass strip.     | 2488 x 840     |
| `logo`       | `logo.png`       | Logo image displayed next to the logo text. | 640 x 220      |
| `background` | `background.png` | Background image behind the pass content.   | 2488 x 2160    |

See the [API reference](/docs/api-reference) for listing, updating and deleting templates.