Update Pass

Update a pass. Changes trigger a push update to the holder's wallet.

PATCH /wallethero-api/passes/:id

Dedicated wallethero-api endpoint

This is an entity-guarded wallethero-api endpoint, not Directus /items/passes/:id. The pass is loaded by id and the caller's workspace membership is checked against its workspace_id. Server-managed columns (id, workspace_id, user_created, date_created, date_updated) are stripped from the body — you cannot move a pass to another workspace.

Identity (first_name, last_name, email, phone, marketing_consent) and custom_fields live on the client, not the pass. Update them via the Clients endpoints (or wh.clients.updateCustomFields(...)). This endpoint only accepts template/notification/pass-display fields.

Authentication

Bearer token — member of the pass's workspace.

Path Parameters

Parameter	Type	Description
id	string (UUID)	Pass identifier

Request Body

All fields are optional — only include the fields you want to change.

Field	Type	Description
pass_template_id	string (UUID)	Switch to a different template (within the same project)
notification	string	Push notification message to send
pass_fields	object	Pass-display overrides (image overrides, seat number, etc.)
client_id	string (UUID)	Re-link the pass to a different client

Example Request

# Template switch + notification
curl -X PATCH "https://api.wallethero.app/wallethero-api/passes/PASS_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "pass_template_id": "GOLD_TEMPLATE_ID",
    "notification": "Welcome to Gold tier!"
  }'

# Identity / custom fields live on the client — update via the clients endpoint
curl -X PATCH "https://api.wallethero.app/wallethero-api/workspace/WORKSPACE_ID/clients/CLIENT_ID" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "custom_fields": { "points": 1600, "last_visit": "2024-01-15" } }'

Response (200)

{
  "data": {
    "id": "pass-uuid",
    "pass_template_id": "gold-template-uuid",
    "notification": "Welcome to Gold tier!",
    "client_id": "client-uuid",
    "date_updated": "2024-01-15T14:30:00Z"
  }
}

SDK Example

// Pass-level update (template switch + notification)
await wh.passes.update("PASS_ID", {
  pass_template_id: "GOLD_TEMPLATE_ID",
  notification: "Welcome to Gold tier!",
});

// Convenience: switch template
await wh.passes.switchTemplate("PASS_ID", "GOLD_TEMPLATE_ID");

// Convenience: send a push notification (update with `notification` set)
await wh.passes.sendNotification("PASS_ID", "Your order is ready for pickup!");

// Client-level update (custom fields). Propagates to all the client's passes —
// the backend recomputes barcode_value and pushes pass updates.
await wh.clients.updateCustomFields("WORKSPACE_ID", "CLIENT_ID", {
  points: 1600,
  last_visit: "2024-01-15",
});

Custom Fields Merge Behavior

Custom fields on the client are merged with existing values when you use wh.clients.updateCustomFields(...). See Pass Custom Fields and Clients for details.

Before:

{ "custom_fields": { "points": 1500, "tier": "Bronze", "member_since": "2024-01-15" } }

Update:

{ "custom_fields": { "points": 1600, "last_visit": "2024-01-15" } }

After:

{
  "custom_fields": {
    "points": 1600,
    "tier": "Bronze",
    "member_since": "2024-01-15",
    "last_visit": "2024-01-15"
  }
}

To remove a field, set it to null.

Push Notifications

Setting notification triggers a push notification to the holder's device:

await wh.passes.update("PASS_ID", {
  notification: "Your order is ready for pickup!",
});

TIP

Push notifications are only delivered if the pass is installed in the user's wallet, the device is online, and notifications are enabled.

Errors

Status	Code	Description
400	INVALID_PAYLOAD	Invalid field values
403	FORBIDDEN	Caller is not a member of the pass's workspace
404	RECORD_NOT_FOUND	Pass not found