Create Pass Template

Create a new pass template.

POST /wallethero-api/workspace/:workspaceId/pass-templates

Dedicated wallethero-api endpoint

This is a workspace-scoped wallethero-api endpoint, not Directus /items/pass_templates. The workspace_id is taken from the path and set on the row server-side. The SDK strips audit fields (id, user_created, date_created, user_updated, date_updated, statistics, passes) before sending.

Authentication

Bearer token — caller must be a member of the workspace in the path.

Path Parameters

Parameter	Type	Description
workspaceId	string (UUID)	Workspace identifier

Request Body

Field	Type	Required	Description
name	string	Yes	Template name
workspace_id	string (UUID)	Yes	Workspace identifier (must match the path)
project_id	string (UUID)	Yes	Project identifier
pass_type	string	Yes	One of: LOYALTY, GIFT_CARD, EVENT_TICKET, OFFER, GENERIC
apple_pass_type_identifier	string	Yes	Apple Pass Type ID (e.g. pass.com.example.loyalty)
uuid	string (UUID)	Yes	Public template identifier
description	string	No	Template description
background_color	string (hex)	No	Background color (e.g. #FF5733)
label_color	string (hex)	No	Label text color
value_color	string (hex)	No	Value text color
logo_text	string	No	Text displayed with the logo
barcode_type	string	No	One of: none, qr, aztec, code128, pdf417
barcode_id	string	No	Field name used as the barcode value
barcode_label	string	No	Label displayed under the barcode
top_field_label	string	No	Header field label
top_field_value	string	No	Header field value (supports interpolation)
front_fields	array<PassField>	No	Primary fields on the pass front
secondary_fields	array<PassField>	No	Secondary fields below the primary row
back_fields	array<PassField>	No	Fields on the back of the pass
show_benefits_on_back	boolean	No	Render tier benefits on the back
show_available_rewards_on_back	boolean	No	Render available rewards on the back
show_active_rewards_on_back	boolean	No	Render active rewards on the back
show_loyalty_portal_link_on_back	boolean	No	Render the loyalty portal link on the back
show_referral_code_on_back	boolean	No	Render the referral code on the back
back_sections_order	array<string>	No	Order of back sections (e.g. benefits, available_rewards, custom:<id>)
locations	array<Location>	No	Location-based notification triggers
location_message	string	No	Message shown when near a location
ios_deeplink_id	number	No	iOS deeplink identifier
ios_deeplink_url	string	No	iOS deeplink URL
tier_id	string (UUID)	No	Tier identifier (loyalty)
tier_label	string	No	Display label for the tier
icon / logo / cover_image	string (UUID)	No	Directus file IDs — see Template Images

PassField Object

Field	Type	Required	Description
label	string	Yes	Field label
value	string	Yes	Field value (supports interpolation)

Location Object

Field	Type	Required	Description
latitude	number	Yes	Latitude coordinate (-90 to 90)
longitude	number	Yes	Longitude coordinate (-180 to 180)
altitude	number	No	Altitude in meters
name	string	No	Location name for reference

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/pass-templates" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold Member Card",
    "workspace_id": "WORKSPACE_ID",
    "project_id": "PROJECT_ID",
    "uuid": "11111111-2222-3333-4444-555555555555",
    "pass_type": "LOYALTY",
    "apple_pass_type_identifier": "pass.com.example.loyalty",
    "background_color": "#1a1a2e",
    "label_color": "#ffffff",
    "value_color": "#ffd700",
    "logo_text": "ACME Rewards",
    "barcode_type": "qr",
    "barcode_id": "id",
    "top_field_label": "POINTS",
    "top_field_value": "{{points}}",
    "front_fields": [
      { "label": "Member", "value": "{{first_name}} {{last_name}}" },
      { "label": "Tier", "value": "{{tier}}" }
    ],
    "back_fields": [
      { "label": "Terms", "value": "Points expire after 12 months of inactivity." }
    ]
  }'

Response (201)

{
  "data": {
    "id": "template-uuid",
    "uuid": "11111111-2222-3333-4444-555555555555",
    "name": "Gold Member Card",
    "pass_type": "LOYALTY",
    "workspace_id": "workspace-uuid",
    "project_id": "project-uuid",
    "apple_pass_type_identifier": "pass.com.example.loyalty",
    "background_color": "#1a1a2e",
    "barcode_type": "qr",
    "front_fields": [
      { "label": "Member", "value": "{{first_name}} {{last_name}}" },
      { "label": "Tier", "value": "{{tier}}" }
    ],
    "date_created": "2024-01-15T10:30:00Z",
    "user_created": "user-uuid"
  }
}

Statistics Object (read-only, present on reads)

Field	Type	Description
passes_count	number	Total passes created from this template
apple_registrations_count	number	Passes installed in Apple Wallet
google_registrations_count	number	Passes installed in Google Wallet
total_registrations_count	number	Total wallet installations

SDK Example

const template = await wh.passTemplates.create({
  name: "Gold Member Card",
  workspace_id: "WORKSPACE_ID",
  project_id: "PROJECT_ID",
  uuid: crypto.randomUUID(),
  pass_type: "LOYALTY",
  apple_pass_type_identifier: "pass.com.example.loyalty",
  background_color: "#1a1a2e",
  label_color: "#ffffff",
  value_color: "#ffd700",
  barcode_type: "qr",
  front_fields: [
    { label: "Member", value: "{{first_name}} {{last_name}}" },
    { label: "Points", value: "{{points}}" },
  ],
});

// Duplicate an existing template (clones it with a new uuid and a "(Copy)" name)
const copy = await wh.passTemplates.duplicate(template.data.id);

Errors

Status	Code	Description
400	INVALID_PAYLOAD	Missing required fields
403	FORBIDDEN	Caller is not a member of the workspace
404	RECORD_NOT_FOUND	Workspace or project not found