Create Pass

Create a new wallet pass and link it to a client.

POST /wallethero-api/workspace/:workspaceId/passes

Dedicated wallethero-api endpoint

This is a workspace-scoped wallethero-api endpoint, not Directus /items/passes. The workspace_id is taken from the path and set on the created row server-side.

Identity (first_name, last_name, email, phone, marketing_consent) and custom_fields live on the client, not the pass. Either pass an existing client_id, or pass client_identity to auto-create/reuse a client by (workspace_id, email).

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	Default	Description
pass_template_id	string (UUID)	Yes	—	Template identifier
project_id	string (UUID)	Yes	—	Project identifier
workspace_id	string (UUID)	Yes	—	Workspace identifier (must match the path)
client_id	string (UUID)	No	null	Existing client to link. Identity and custom fields are read from this client
client_identity	object	No	—	Provide instead of client_id to auto-create/reuse a client by (workspace_id, email)
notification	string	No	null	Initial push notification message
metadata	object	No	—	Arbitrary metadata stored with the request
enroll_loyalty_program	boolean	No	true	Enroll the resolved client in the loyalty program. An already-enrolled client keeps their original enrollment date

client_identity Object

Field	Type	Required	Description
email	string	Yes	Client email — used to look up or create the client
first_name	string	No	Client first name
last_name	string	No	Client last name
phone	string	No	Client phone
marketing_consent	boolean	No	Marketing consent flag
source	string	No	Acquisition source label
custom_fields	object	No	Workspace data-model custom fields applied to the client (routed through updateClientFields so field-change events fire)

Example Request

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/passes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pass_template_id": "TEMPLATE_ID",
    "project_id": "PROJECT_ID",
    "workspace_id": "WORKSPACE_ID",
    "client_id": "CLIENT_ID"
  }'

Auto-create the client by identity instead of passing client_id:

curl -X POST "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/passes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pass_template_id": "TEMPLATE_ID",
    "project_id": "PROJECT_ID",
    "workspace_id": "WORKSPACE_ID",
    "client_identity": {
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "custom_fields": { "tier": "Bronze", "points": 0 }
    }
  }'

Response (201)

{
  "data": {
    "id": "pass-uuid",
    "pass_template_id": "template-uuid",
    "project_id": "project-uuid",
    "workspace_id": "workspace-uuid",
    "client_id": "client-uuid",
    "apple_pass_url": "https://api.wallethero.app/...",
    "apple_qrcode_url": "https://api.wallethero.app/...",
    "google_pass_url": "https://pay.google.com/gp/v/save/...",
    "google_qrcode_url": "https://api.wallethero.app/...",
    "date_created": "2024-01-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
id	string (UUID)	Unique pass identifier
pass_template_id	string (UUID)	Template used for this pass
project_id	string (UUID)	Project this pass belongs to
workspace_id	string (UUID)	Workspace this pass belongs to
client_id	string (UUID)	Linked client identifier
notification	string	Last notification sent
pass_fields	object	Pass-display overrides
barcode_value	string	Pre-interpolated barcode value
apple_pass_url	string (URL)	Direct download URL for Apple Wallet pass
apple_qrcode_url	string (URL)	QR code URL for Apple Wallet pass
google_pass_url	string (URL)	Google Wallet save URL
google_qrcode_url	string (URL)	QR code URL for Google Wallet pass
date_created	string (ISO 8601)	Creation timestamp

To return the linked client inline (identity + custom_fields), expand the relation:

GET /wallethero-api/passes/{pass_id}?fields=*,client.*

SDK Example

// Link an existing client
const pass = await wh.passes.create({
  pass_template_id: "TEMPLATE_ID",
  project_id: "PROJECT_ID",
  workspace_id: "WORKSPACE_ID",
  client_id: "CLIENT_ID",
});

console.log("Apple Pass URL:", pass.data.apple_pass_url);
console.log("Google Wallet URL:", pass.data.google_pass_url);

// Auto-create the client by identity
const pass = await wh.passes.create({
  pass_template_id: "TEMPLATE_ID",
  project_id: "PROJECT_ID",
  workspace_id: "WORKSPACE_ID",
  client_identity: {
    email: "[email protected]",
    first_name: "John",
    last_name: "Doe",
    custom_fields: { tier: "Bronze", points: 0 },
  },
});

Bulk Create

bulkCreateFromTemplate issues one create call per pass (each scoped to its own workspace):

const result = await wh.passes.bulkCreateFromTemplate("TEMPLATE_ID", [
  { workspace_id: "WORKSPACE_ID", project_id: "PROJECT_ID", client_id: "CLIENT_A" },
  { workspace_id: "WORKSPACE_ID", project_id: "PROJECT_ID", client_id: "CLIENT_B" },
]);

Sending the Pass to Users

After creating a pass, you can:

1. Direct Download: Send the apple_pass_url to the user.
2. QR Code: Display apple_qrcode_url or google_qrcode_url for scanning.
3. Email: Re-send via wh.passes.resendEmail(passId) (POST /wallethero-api/pass/resend), or use distributions to collect and email passes.

await wh.passes.resendEmail(pass.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	Template, project, or workspace not found