API reference · Passes

Send a notification

POST/v1/passes/{serial}/notifications1 operationSafe to retry with Idempotency-Key

Shows a message on holders' lock screens, and keeps it in the pass's Latest message field.

Path

serialstringrequired

The pass's serialNumber.

Body

messagestring, up to 256 charactersrequired

What holders see.

Answer

200Sent

The same as an update's, with the message. firstMessage is true when the pass had no Latest message field before: this one adds it, and may not show a banner.

Errors

Every error has the same shape: see Errors.

Status	Code	When
400	`validation_error`	No message, it's too long, or it has a placeholder such as `{{name}}`: messages are sent exactly as written.
404	`not_found`	No pass with that serial number in this workspace.
409	`pass_not_active`	It's revoked, or not published yet.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
429	`usage_limit_exceeded`	This month's operations on your plan are used up.
429	`workspace_limit_reached`	This workspace's monthly limit, set by its organization, is used up.
429	`platform_usage_limit`	A test pass, and the 1,000 test operations a month are used up.

To tell every pass, or the ones a search finds, at once, send a broadcast.

Request

curl "https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88/notifications" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: promo-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Double points this weekend"
  }'

const res = await fetch("https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88/notifications", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "promo-1042",
  },
  body: JSON.stringify({
    "message": "Double points this weekend"
  }),
});
const data = await res.json();

import os

import requests

res = requests.post(
    "https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88/notifications",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "promo-1042"},
    json={
        "message": "Double points this weekend",
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/passes/9f904677-e06d-4b0f-8404-878ff1066f88/notifications");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: promo-1042",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "message" => "Double points this weekend",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

200 Sent

{
  "serialNumber": "9f904677-e06d-4b0f-8404-878ff1066f88",
  "version": 5,
  "lastUpdated": "2026-10-08T19:31:12.000Z",
  "notifiedDevices": 1,
  "unchanged": false,
  "notified": true,
  "platforms": {
    "apple": "queued",
    "google": "queued"
  },
  "notification": {
    "message": "Double points this weekend",
    "firstMessage": false
  }
}