Messages

Send push notifications to passes already saved in users' wallets. Target a single pass or broadcast to every pass of a template.

Send a Message

POST /api/v1/messages

Field	Type		Description
pass_id	UUID	one-of	Send to exactly one pass.
template_id	UUID	one-of	Broadcast to every active pass of this template.
header	string	required	≤ 100 chars. Shown as the notification title.
body	string	required	≤ 500 chars. Notification body.

Either pass_id or template_id — not both, not neither. The Validator returns 400 otherwise.

POST /api/v1/messages

{
  "pass_id": "57725a27-...",
  "header":  "5x points this weekend",
  "body":    "Earn 5x points on every purchase Sat-Sun."
}

● 202 Accepted

{
  "id":              "b08f5d12-...",
  "pass_id":         "57725a27-...",
  "header":          "5x points this weekend",
  "body":            "Earn 5x points on every purchase Sat-Sun.",
  "status":          "pending",
  "affected_passes": 1,
  "job_id":          "...",
  "created_at":      "2026-05-18T10:00:00Z"
}

Broadcast to a Template

When template_id is supplied, affected_passes is the live count of active, non-revoked passes for that template at the moment of the request. The count is re-computed on every GET so it reflects real-time changes.

List & Get

GET /api/v1/messages?pass_id={id}&page=1&page_size=20

GET /api/v1/messages/{id}

GET /api/v1/passes/{id}/messages

Provider behaviour

Google Wallet: uses the native Addmessage upstream endpoint — the notification appears as a pass banner.

Apple Wallet: regenerates the .pkpass with the message as a back-field and pushes an APNs notification so devices re-pull.