API reference · Templates

Save a template's changes

PUT/v1/templates/{slug}Free; 1 operation a pass it updatesSafe to retry with Idempotency-Key

Replaces its design and rules. Passes made from it keep their design until you update them, now ("updatePasses": "all") or later.

Path

slugstringrequired

The template's slug. org:<slug> for one your organization shares with this workspace (those can only be read).

Body

The template, whole, as it should now be. Beside it:

updatePassesall · none

all gives every pass made from it the new design, in the background; installed passes refresh. Default none.

fillobject

With all: a value for each required placeholder the new design adds, for the passes made before it.

Answer

200Saved

changed is false when the design and rules are the same, so the version stays. update is the update of its passes that started, or null.

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.
403	`organization_template`	It's your organization's: change it in the dashboard, or duplicate it to make your own.
404	`not_found`	No template with that slug here.
409	`template_update_in_progress`	Its passes are still being updated: save when that's finished.
409	`template_changed`	Someone saved it at the same moment. Get it again and retry.
409	`idempotency_conflict`	The Idempotency-Key was already used for a different request.
422	`slug_immutable`	The body's `slug` isn't this template's.
422	`placeholder_fill_required`	The new design adds a required placeholder with no default: give it a value in `fill`. `missing` lists them.
429	`template_update_over_allowance`	Updating its passes would go past this month's operations. Nothing is saved; `preview` says what's left.

Request

curl -X PUT "https://api.walletpassapi.com/v1/templates/gold-member" \
  -H "Authorization: Bearer $WALLET_API_KEY" \
  -H "Idempotency-Key: gold-member-v2" \
  -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",
      "auxiliaryFields": [
        {
          "key": "tier",
          "label": "Tier",
          "value": "{{tier}}"
        }
      ]
    },
    "placeholders": [
      {
        "key": "points",
        "type": "number"
      },
      {
        "key": "member_id",
        "label": "Member ID"
      }
    ],
    "holderRequired": {
      "name": true
    },
    "updatePasses": "all",
    "fill": {
      "tier": "Gold"
    }
  }'

const res = await fetch("https://api.walletpassapi.com/v1/templates/gold-member", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.WALLET_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": "gold-member-v2",
  },
  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",
      "auxiliaryFields": [
        {
          "key": "tier",
          "label": "Tier",
          "value": "{{tier}}"
        }
      ]
    },
    "placeholders": [
      {
        "key": "points",
        "type": "number"
      },
      {
        "key": "member_id",
        "label": "Member ID"
      }
    ],
    "holderRequired": {
      "name": true
    },
    "updatePasses": "all",
    "fill": {
      "tier": "Gold"
    }
  }),
});
const data = await res.json();

import os

import requests

res = requests.put(
    "https://api.walletpassapi.com/v1/templates/gold-member",
    headers={"Authorization": f"Bearer {os.environ['WALLET_API_KEY']}", "Idempotency-Key": "gold-member-v2"},
    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",
            "auxiliaryFields": [
                {
                    "key": "tier",
                    "label": "Tier",
                    "value": "{{tier}}",
                },
            ],
        },
        "placeholders": [
            {
                "key": "points",
                "type": "number",
            },
            {
                "key": "member_id",
                "label": "Member ID",
            },
        ],
        "holderRequired": {
            "name": True,
        },
        "updatePasses": "all",
        "fill": {
            "tier": "Gold",
        },
    },
)
data = res.json()

<?php

$ch = curl_init("https://api.walletpassapi.com/v1/templates/gold-member");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "PUT",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("WALLET_API_KEY"),
        "Content-Type: application/json",
        "Idempotency-Key: gold-member-v2",
    ],
    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",
            "auxiliaryFields" => [
                [
                    "key" => "tier",
                    "label" => "Tier",
                    "value" => "{{tier}}",
                ],
            ],
        ],
        "placeholders" => [
            [
                "key" => "points",
                "type" => "number",
            ],
            [
                "key" => "member_id",
                "label" => "Member ID",
            ],
        ],
        "holderRequired" => [
            "name" => true,
        ],
        "updatePasses" => "all",
        "fill" => [
            "tier" => "Gold",
        ],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true);

200 Saved

{
  "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": 2,
    "passes": 1200,
    "outdated": 1200,
    "organization": false,
    "createdAt": "2026-10-08T19:31:12.000Z",
    "updatedAt": "2026-10-08T19:31:12.000Z"
  },
  "changed": true,
  "update": {
    "id": "bc_q4n7w2k9x1m3p5r8",
    "status": "sending",
    "total": 1200,
    "updated": 0,
    "skipped": 0,
    "failed": 0,
    "lastError": null,
    "createdAt": "2026-10-08T19:31:12.000Z",
    "completedAt": null
  }
}