Image Assets

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.

{
  "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

Upload an image using Create Image Asset with the image data and type
Get the id from the response
Reference the id in your pass templateOverride when creating or updating a pass

Using Image Assets in templateOverride

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.

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

{
  "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 and Batch Pass Update 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.

{
  "pass": {
    "templateOverride": {
      "bannerImage": "https://example.com/banner.png"
    }
  }
}

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

Introduction

Entities

Pass Templates

Passes

Readers

Scans

Loyalty

Webhook Subscriptions

Webhooks

Batches

Image Assets

Supported image types

Watermark

Workflow

Using Image Assets in templateOverride

Using Image Assets in Batch Operations

Deprecated format

​Supported image types

​Watermark

​Workflow

​Using Image Assets in templateOverride

​Using Image Assets in Batch Operations

​Deprecated format

Supported image types

Watermark

Workflow

Using Image Assets in templateOverride

Using Image Assets in Batch Operations

Deprecated format