API reference · Templates

Create a template

POST/v1/templatesFreeSafe to retry with Idempotency-Key

A pass design with {{placeholders}} where each pass has its own values. Make passes from it with Create a pass.

Body

The template: name and design, with a rule for any placeholder that isn't required text.

Answer

201Created

keys lists the design's placeholders in the order a pass reads.

Errors

Every error has the same shape: see Errors.

Status	Code	When
400	`validation_error`	A field is wrong or unknown, a `{{…}}` isn't a placeholder, or a rule names one the design doesn't use. `field` says where, such as `design.primaryFields.0.value`.
422	`unknown_issuer`	No issuer with that slug here.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
409	`template_slug_taken`	This workspace already has a template with that slug.

The design is checked as a pass with sample values, so a mistake is refused now, not when a pass is made from it.

Request

curl "https://api.walletpassapi.com/v1/templates" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: gold-member-template" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gold member",
    "slug": "gold-member",
    "design": {
      "organizationName": "Acme Coffee",
      "logoText": "Acme",
      "style": "loyalty",
      "primaryFields": [
        {
          "key": "points",
          "label": "Points",
          "value": "{{points}}",
          "changeMessage": "You now have %@ points"
        }
      ],
      "secondaryFields": [
        {
          "key": "member",
          "label": "Member",
          "value": "{{holder.name}}"
        }
      ],
      "barcodeValue": "{{member_id}}",
      "barcodeFormat": "QR"
    },
    "placeholders": [
      {
        "key": "points",
        "type": "number"
      },
      {
        "key": "member_id",
        "label": "Member ID"
      }
    ],
    "holderRequired": {
      "name": true
    }
  }'

const res = await fetch("https://api.walletpassapi.com/v1/templates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "gold-member-template",
  },
  body: JSON.stringify({
    "name": "Gold member",
    "slug": "gold-member",
    "design": {
      "organizationName": "Acme Coffee",
      "logoText": "Acme",
      "style": "loyalty",
      "primaryFields": [
        {
          "key": "points",
          "label": "Points",
          "value": "{{points}}",
          "changeMessage": "You now have %@ points"
        }
      ],
      "secondaryFields": [
        {
          "key": "member",
          "label": "Member",
          "value": "{{holder.name}}"
        }
      ],
      "barcodeValue": "{{member_id}}",
      "barcodeFormat": "QR"
    },
    "placeholders": [
      {
        "key": "points",
        "type": "number"
      },
      {
        "key": "member_id",
        "label": "Member ID"
      }
    ],
    "holderRequired": {
      "name": true
    }
  }),
});
const data = await res.json();

import os

import requests

res = requests.post(
    "https://api.walletpassapi.com/v1/templates",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "gold-member-template"},
    json={
        "name": "Gold member",
        "slug": "gold-member",
        "design": {
            "organizationName": "Acme Coffee",
            "logoText": "Acme",
            "style": "loyalty",
            "primaryFields": [
                {
                    "key": "points",
                    "label": "Points",
                    "value": "{{points}}",
                    "changeMessage": "You now have %@ points",
                },
            ],
            "secondaryFields": [
                {
                    "key": "member",
                    "label": "Member",
                    "value": "{{holder.name}}",
                },
            ],
            "barcodeValue": "{{member_id}}",
            "barcodeFormat": "QR",
        },
        "placeholders": [
            {
                "key": "points",
                "type": "number",
            },
            {
                "key": "member_id",
                "label": "Member ID",
            },
        ],
        "holderRequired": {
            "name": True,
        },
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/templates");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: gold-member-template",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "name" => "Gold member",
        "slug" => "gold-member",
        "design" => [
            "organizationName" => "Acme Coffee",
            "logoText" => "Acme",
            "style" => "loyalty",
            "primaryFields" => [
                [
                    "key" => "points",
                    "label" => "Points",
                    "value" => "{{points}}",
                    "changeMessage" => "You now have %@ points",
                ],
            ],
            "secondaryFields" => [
                [
                    "key" => "member",
                    "label" => "Member",
                    "value" => "{{holder.name}}",
                ],
            ],
            "barcodeValue" => "{{member_id}}",
            "barcodeFormat" => "QR",
        ],
        "placeholders" => [
            [
                "key" => "points",
                "type" => "number",
            ],
            [
                "key" => "member_id",
                "label" => "Member ID",
            ],
        ],
        "holderRequired" => [
            "name" => true,
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

201 Created

{
  "template": {
    "slug": "gold-member",
    "name": "Gold member",
    "design": {
      "organizationName": "Acme Coffee",
      "logoText": "Acme",
      "style": "loyalty",
      "primaryFields": [
        {
          "key": "points",
          "label": "Points",
          "value": "{{points}}",
          "changeMessage": "You now have %@ points"
        }
      ],
      "secondaryFields": [
        {
          "key": "member",
          "label": "Member",
          "value": "{{holder.name}}"
        }
      ],
      "barcodeValue": "{{member_id}}",
      "barcodeFormat": "QR"
    },
    "placeholders": [
      {
        "key": "points",
        "type": "number",
        "required": true
      },
      {
        "key": "member_id",
        "label": "Member ID",
        "type": "text",
        "required": true
      }
    ],
    "keys": [
      "points",
      "holder.name",
      "member_id"
    ],
    "holderRequired": {
      "name": true,
      "email": false
    },
    "issuer": null,
    "installHeadline": null,
    "version": 1,
    "passes": 0,
    "outdated": 0,
    "organization": false,
    "createdAt": "2026-10-08T19:31:12.000Z",
    "updatedAt": "2026-10-08T19:31:12.000Z"
  }
}