Pass Template Images

Upload and manage the icon, logo, and cover_image of a pass template.

Two endpoints are involved

Image handling is a two-step flow:

1. Upload the file to the Directus-native files endpoint: POST /files (multipart form-data). This returns a file with an id.
2. Attach the file ID to the template via the dedicated PATCH /wallethero-api/pass-templates/:id endpoint, setting icon, logo, or cover_image to the file id.

There is no form-data upload directly on the template endpoint. The SDK's image helpers do both steps for you.

Auth: Bearer token. The file upload uses the same Bearer token; the template PATCH additionally requires workspace membership.

Image Types

Image	Description	Recommended Size
icon	App icon (required for Apple)	58x58px @2x, 87x87px @3x
logo	Logo displayed on the pass	320x100px
cover_image	Header/strip image	640x168px (Loyalty), 640x220px (Event)

Step 1 — Upload the File

POST /files

Directus-native multipart upload. The SDK routes pass images into dedicated folders by type.

curl -X POST "https://api.wallethero.app/files" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/icon.png" \
  -F "title=Pass icon image"

Response (200)

{ "data": { "id": "icon-file-uuid", "filename_download": "icon.png" } }

Step 2 — Attach the File ID to the Template

PATCH /wallethero-api/pass-templates/:id

Set the image field to the file id returned in step 1.

curl -X PATCH "https://api.wallethero.app/wallethero-api/pass-templates/TEMPLATE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "icon": "icon-file-uuid",
    "logo": "logo-file-uuid",
    "cover_image": "cover-file-uuid"
  }'

Response (200)

{
  "data": {
    "id": "template-uuid",
    "icon": "icon-file-uuid",
    "logo": "logo-file-uuid",
    "cover_image": "cover-file-uuid"
  }
}

SDK Example

The SDK helpers run both steps. Pass a File/Blob (uploaded for you) or an existing file ID string (attached directly).

// Upload (or reference) all images at once
await wh.passTemplates.updateImages("TEMPLATE_ID", {
  icon: iconFile,                 // File | Blob | existing file-id string
  logo: logoFile,
  cover_image: "existing-file-uuid",
});

// Or one at a time
await wh.passTemplates.uploadIcon("TEMPLATE_ID", iconFile);
await wh.passTemplates.uploadLogo("TEMPLATE_ID", logoFile);
await wh.passTemplates.uploadCoverImage("TEMPLATE_ID", coverFile);

Remove an Image

Set the field to null via the template PATCH:

curl -X PATCH "https://api.wallethero.app/wallethero-api/pass-templates/TEMPLATE_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "cover_image": null }'

await wh.passTemplates.removeImages("TEMPLATE_ID", ["cover_image"]);

Display an Image

Images are served by the Directus-native assets endpoint:

GET https://api.wallethero.app/assets/{file-id}

With on-the-fly transformations:

GET https://api.wallethero.app/assets/{file-id}?width=200&height=200&fit=cover

The SDK builds these URLs for you:

const template = await wh.passTemplates.get("TEMPLATE_ID");

// Plain URLs
const { icon, logo, cover_image } = wh.passTemplates.getImageUrls(template.data);

// Small/medium/large variants per image
const optimized = wh.passTemplates.getOptimizedImageUrls(template.data);
console.log(optimized.icon?.medium);

Image Guidelines

Icon

• Required for Apple Wallet passes.
• Simple, recognizable symbol; PNG with transparency supported.
• Shown in the wallet app list.

Logo

• Displayed at the top of the pass; include your brand mark.
• Keep text legible at small sizes; PNG recommended.

Cover Image (Strip / Header)

• Spans the width of the pass; good for branding or event imagery.
• Size varies by pass type; consider overlay text legibility.