> ## Documentation Index
> Fetch the complete documentation index at: https://docs.passentry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Image Assets

> Upload images once and reference them by ID across multiple passes

Image Assets allow you to upload images once and reference them by ID when creating or updating passes. Instead of providing a raw image URL every time, you upload the image to PassEntry and use the returned `imageAssetId` in your `templateOverride`.

Images can be provided as a **direct URL** or **base64 encoded data**. Supported formats: **PNG, JPG, WebP**.

### Supported image types

| Type        | Description                                          |
| ----------- | ---------------------------------------------------- |
| `banner`    | Banner image displayed at the top of the pass        |
| `logo`      | Logo image on the pass                               |
| `thumbnail` | Thumbnail image (generic pass type only, Apple only) |

### Watermark

If your organisation has watermarking enabled, a `watermark` object is required when uploading `banner` images. The watermark is applied automatically during processing.

```json theme={null}
{
  "imageAsset": {
    "image": "https://example.com/silver_tier_banner.png",
    "imageType": "banner",
    "watermark": {
      "color": "light",
      "position": "bottomRight"
    }
  }
}
```

| Field      | Values                                             |
| ---------- | -------------------------------------------------- |
| `color`    | `dark`, `light`                                    |
| `position` | `bottomLeft`, `bottomRight`, `topLeft`, `topRight` |

### Workflow

1. **Upload an image** using [Create Image Asset](/api-reference/v1/image-assets/create-image-asset) with the image data and type
2. **Get the `id`** from the response
3. **Reference the `id`** in your pass `templateOverride` when creating or updating a pass

### Using Image Assets in templateOverride

<Note>
  Template overrides must be enabled for your organisation. Contact support to request access. Requests made without this feature enabled will return a **403 Forbidden** error.
</Note>

When creating or updating a pass, reference an image asset by its ID in the `templateOverride` object:

```json theme={null}
{
  "pass": {
    "templateOverride": {
      "bannerImage": {
        "imageAssetId": "19cb334f9696e64e10e7759f0"
      },
      "logoImage": {
        "imageAssetId": "29dc445g0797f75f21f8860g1"
      }
    }
  }
}
```

### Using Image Assets in Batch Operations

You can reference image assets in CSV batch operations using the following columns:

| CSV Column                          | Description                                                     |
| ----------------------------------- | --------------------------------------------------------------- |
| `override_banner_image_asset_id`    | UUID of a processed banner image asset                          |
| `override_logo_image_asset_id`      | UUID of a processed logo image asset                            |
| `override_thumbnail_image_asset_id` | UUID of a processed thumbnail image asset (generic passes only) |

For batch updates, set a column to the literal string `null` to remove an image asset override.

See the [Batch Pass Creation](/documentation/bulk-operations/batch-pass-creation/guide) and [Batch Pass Update](/documentation/bulk-operations/batch-pass-update/guide) guides for full details.

### Deprecated format

The previous flat URL format for image overrides is deprecated but still supported. Image URLs must use **HTTPS** or be a **base64-encoded data URI** (`data:image/...`). Plain HTTP URLs are rejected.

```json theme={null}
{
  "pass": {
    "templateOverride": {
      "bannerImage": "https://example.com/banner.png"
    }
  }
}
```

We recommend migrating to the `imageAssetId` object format for better image management and reduced duplication.