API reference · Passes

Create a pass

POST/v1/passes1 operationSafe to retry with Idempotency-Key

Builds the Apple Wallet pass and the Google Wallet pass from one description, and gives you an install page for both.

Body

The pass's fields: organizationName, and logoText or primaryFields, at least. Or a template's slug with its values instead of the fields. Beside them:

issuerstring

Which of your issuers signs it: its slug, or org:<slug> for your organization's. Left out, your workspace's default. A pass keeps its set for life.

dataobject

Values for the placeholders in its text, such as { "points": 120 }.

holderobject

The holder's name and email. Kept with the pass, so you can find one person's passes.

templatestring

Make it from this template instead of sending fields: its slug, or org:<slug> for your organization's. Send data, holder and an externalId with it.

Answer

201Created

shareUrl is the install page to send the holder. platforms says whether each wallet's pass was built: built, or no_credential when the issuer has none for that wallet. applePass (the signed .pkpass, base64) and googleSaveUrl come with a built one.

Errors

Every error has the same shape: see Errors.

Status	Code	When
400	`invalid_json`	The body isn't JSON.
400	`validation_error`	A field is missing, too long or unknown. `field` names it; a near miss suggests the field you meant.
400	`placeholder_missing`	A required placeholder has no value. `missing` lists every one.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
409	`external_id_conflict`	Another pass in this workspace has that `externalId`.
422	`unknown_issuer`	No issuer with that slug here.
422	`unknown_template`	No template with that slug here (or shared with this workspace).
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.

Keep the serialNumber: it's how you update, notify and revoke the pass.
Until you add your own credentials, passes are signed with ours and marked as test passes.

Request

curl "https://api.walletpassapi.com/v1/passes" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationName": "Acme Coffee",
    "logoText": "Acme",
    "style": "loyalty",
    "primaryFields": [
      {
        "key": "points",
        "label": "Points",
        "value": "120",
        "changeMessage": "You now have %@ points"
      }
    ],
    "barcodeValue": "MEMBER-1042",
    "barcodeFormat": "QR",
    "externalId": "crm-1042"
  }'

const res = await fetch("https://api.walletpassapi.com/v1/passes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "order-1042",
  },
  body: JSON.stringify({
    "organizationName": "Acme Coffee",
    "logoText": "Acme",
    "style": "loyalty",
    "primaryFields": [
      {
        "key": "points",
        "label": "Points",
        "value": "120",
        "changeMessage": "You now have %@ points"
      }
    ],
    "barcodeValue": "MEMBER-1042",
    "barcodeFormat": "QR",
    "externalId": "crm-1042"
  }),
});
const data = await res.json();

import os

import requests

res = requests.post(
    "https://api.walletpassapi.com/v1/passes",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "order-1042"},
    json={
        "organizationName": "Acme Coffee",
        "logoText": "Acme",
        "style": "loyalty",
        "primaryFields": [
            {
                "key": "points",
                "label": "Points",
                "value": "120",
                "changeMessage": "You now have %@ points",
            },
        ],
        "barcodeValue": "MEMBER-1042",
        "barcodeFormat": "QR",
        "externalId": "crm-1042",
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/passes");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: order-1042",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "organizationName" => "Acme Coffee",
        "logoText" => "Acme",
        "style" => "loyalty",
        "primaryFields" => [
            [
                "key" => "points",
                "label" => "Points",
                "value" => "120",
                "changeMessage" => "You now have %@ points",
            ],
        ],
        "barcodeValue" => "MEMBER-1042",
        "barcodeFormat" => "QR",
        "externalId" => "crm-1042",
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

201 Created

{
  "serialNumber": "9f904677-e06d-4b0f-8404-878ff1066f88",
  "status": "active",
  "issuer": "default",
  "shareUrl": "https://app.walletpassapi.com/p/4MOhErCigjeasw-2epMpEkFatq4PNdPYNZqIxXwq5r",
  "createdAt": "2026-10-08T19:31:12.000Z",
  "platforms": {
    "apple": "built",
    "google": "built"
  },
  "applePass": "UEsDBBQAAAAIAA…",
  "googleSaveUrl": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiJ9…"
}