Skip to content
Help Center Guide · Pass IssuanceOnboarding Phase 3
4 min readVerified 2026-11-16

Create Individual Passes

Generate a single pass from a published template with explicit customer attributes and an immediate download/QR preview link.

In This Guide

Interactive UI Walkthroughs

Open in 6-Phase Onboarding Guide

Inspect exact dashboard panels, controls, and zoomed callouts related to this guide.

Zoomed UI focus
Key UI elements

Create single pass & Quick Actions (Zoomed)

Click '+ Create pass' in the header or 'Create single pass' under Quick Actions to generate a test pass from your published template.

Overview

Individual pass issuance allows operators and backend integrations to generate a single personalized digital wallet card from any PUBLISHED template. Whether triggered manually from the Dashboard's Create pass drawer or programmatically via REST API, Passinstance assigns a cryptographically unique serialNumber and authenticationToken, hydrates all dynamic {variable} fields, signs the Apple .pkpass bundle and Google Wallet JWT, and returns an immediate smart distribution URL (passAccessUrl).

Template quick actions to create a single pass
Template quick actions to create a single pass

System Architecture: Single Pass Issuance & Idempotent Upsert

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SINGLE PASS ISSUANCE & IDEMPOTENT UPSERT
STAGE 01 DASHBOARD DRAWER / CRM / POS BACKEND
Standard Issuance: POST/api/v1/passes (request payload)
Idempotent Upsert: POST/api/v1/passes/upsert-by-external-id
STAGE 02 PASS ISSUANCE SERVICE (Pass Issuance Engine)
1
Verifies target Template is PUBLISHED & scoped to workspace (customerId)
2
Evaluates composite key (customerId, externalId) for idempotent deduplication
3
Generates unique serialNumber & 32-byte hex authenticationToken
4
Validates attributes structured JSON against Template Custom Property schema
5
Persists Pass row (status: ACTIVE) & initializes pass mechanic ledger
STAGE 03 WALLET SIGNING & SMART LINK PACKAGING
Generates smart download link (passAccessUrl) & QR code endpoint
Prepares signed Apple .pkpass stream & Google Wallet Save JWT
Returns API response (request payload) with 201 Created or 200 OK

Issuing a Single Pass Manually in the Dashboard

  1. 1
    Navigate to your Published template overview page.
  2. 2
    Click Create pass in the top header (or under Quick actions).
  3. 3
    Fill in every Required Custom Property marked on the form (for example: customer name, email/phone if needed for sendouts, initial stamp count, or externalId).
  4. 4
    Submit to generate the pass immediately.
  5. 5
    Copy the unique Download URL (passAccessUrl), display the Installation QR code to scan with a smartphone, or trigger a delivery email directly from the pass detail drawer.

Prerequisites: Publish your template (POST /api/v1/templates/:id/publish) with valid Apple Pass Type ID / Google Wallet credentials before issuing live passes. Internally, resolvePassCreationTemplateId resolves templateId to its base PRODUCTION/PUBLISHED revision and rejects DELETING/DELETED templates (BadRequestException / NotFoundException).

Programmatic Issuance API Reference

1. Create a New Pass (POST /api/v1/passes)

Creates a new pass record via request payload, honoring an optional HTTP Idempotency-Key header (idempotencyKey, max 128 chars matching [A-Za-z0-9._:-]+, protected by SHA-256 request digest) and optional query params ?includePassSource=apple|google and ?pin=.

request payload Request Parameters

FieldTypeRequiredDescription
templateIdstring (UUID)YesTemplate UUID (automatically resolved to its live PRODUCTION/PUBLISHED base row).
externalIdstringOptionalTenant-unique CRM/POS/order identifier (max 255 chars; enforced unique per live non-deleted pass via @@unique([customerId, externalId])).
serialNumberstringOptionalCustom unique serial number (generated automatically if omitted).
barcodeValuestringOptionalExplicit barcode payload. Defaults to template barcode config or generated value.
barcodeAltText / barcodeAlternativeTextstringOptionalHuman-readable caption printed beneath the barcode for manual cashier entry.
attributesRecord<string, any>OptionalKey-value structured JSON dictionary matching your template's Custom Property keys.
expirationDatestringOptionalExpiration date/time (<= 10 years in the future, parsed in workspace timezone).
validityAsOfDate / validAsOfDatestringOptionalStart validity date/time (issuedDate).
enableDownloadUntilstringOptionalDownload cut-off ("YYYY-MM-DD HH:mm" or ISO timestamp).
sharingProhibitedbooleanOptionalOverrides template anti-sharing setting (limitToOneActivePerPass).
validationPlacesstring[]OptionalAllowed validation place overrides when enabled on the template.
skipDistributeOnCreatebooleanOptionalSuppresses automatic post-creation sendouts (email/SMS) when issuing via API.

Example Request

POST /api/v1/passes?includePassSource=google Headers: X-API-Key: <API_KEY> | Content-Type: application/json | Idempotency-Key: crm_usr_44910_v1

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "serialNumber": "PI-GOLD-2026-44910",
  "barcodeValue": "PI-GOLD-2026-44910",
  "barcodeAltText": "44910-GOLD",
  "expirationDate": "2027-12-31 23:59",
  "attributes": {
    "firstName": "Marcus",
    "lastName": "Vance",
    "email": "marcus.vance@example.com",
    "pointsBalance": 500,
    "memberTier": "Gold"
  }
}

Example Response (API response envelope)

JSON
{
  "success": true,
  "data": {
    "id": "pass_01j8k9m2n3p4q5r6",
    "templateId": "tmpl_01hxyz987654321",
    "customerId": "cust_ws_88219",
    "externalId": "crm_usr_44910",
    "bundleId": null,
    "idempotencyKey": "crm_usr_44910_v1",
    "serialNumber": "PI-GOLD-2026-44910",
    "authenticationToken": "a9f4e2c81b7d60359e12c4b8f7a6d5e0",
    "downloadCode": "dl_94f8a1",
    "barcodeValue": "PI-GOLD-2026-44910",
    "barcodeAltText": "44910-GOLD",
    "status": "ACTIVE",
    "lifecycleStatus": "ACTIVE",
    "walletVoidStatus": "NONE",
    "appleArtifactStatus": "NOT_GENERATED",
    "googleArtifactStatus": "READY",
    "downloadUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "passAccessUrl": "https://app.passinstance.com/p/pass_01j8k9m2n3p4q5r6",
    "attributes": {
      "firstName": "Marcus",
      "lastName": "Vance",
      "email": "marcus.vance@example.com",
      "pointsBalance": 500,
      "memberTier": "Gold"
    },
    "expirationDate": "2027-12-31T23:59:00.000Z",
    "createdAt": "2026-11-15T15:04:12.000Z"
  },
  "description": "Pass created successfully",
  "errors": [],
  "statusCode": 201
}

Tip — Multi-Pass Bundling (bundleId): If you create companion passes for a household, flight leg, or event VIP order, assign them to a pass bundle (/api/v1/bundles/upsert or PassProject) so Pass.bundleId groups up to 10 passes into a unified .pkpasses / multi-card claim link.

2. Idempotent Upsert & Lookup by External ID (request payload)

In webhook-driven integrations (Shopify, HubSpot, or POS checkouts), network retries can fire the same request repeatedly. Passinstance provides dedicated externalId endpoints scoped to your live tenant passes (archivedAt: null):

  • POST /api/v1/passes/upsert-by-external-id: Creates a pass if no live pass matches externalId (action: "CREATED"), or merges attributes, expirationDate, status (pass status), and optional changeMessage (<=500 chars) onto the existing pass (action: "UPDATED").
  • PUT /api/v1/passes/by-external-id/:externalId: Upserts using the path :externalId parameter (externalId in the body must match or can be omitted).
  • GET /api/v1/passes/by-external-id/:externalId: Directly fetches the live pass by externalId without storing internal UUIDs externally.

Example Request

POST /api/v1/passes/upsert-by-external-id Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "externalId": "crm_usr_44910",
  "status": "ACTIVE",
  "changeMessage": "Tier updated to Platinum (%@ pts)",
  "attributes": {
    "pointsBalance": 750,
    "memberTier": "Platinum"
  }
}

Example Response (200 OK)

JSON
{
  "success": true,
  "data": {
    "pass": {
      "id": "pass_01j8k9m2n3p4q5r6",
      "externalId": "crm_usr_44910",
      "serialNumber": "PI-GOLD-2026-44910",
      "status": "ACTIVE",
      "walletVoidStatus": "QUEUED"
    },
    "action": "UPDATED"
  },
  "description": "Pass updated successfully",
  "errors": [],
  "statusCode": 200
}

For high-volume CSV onboarding or array batch generation, see Bulk Pass Creation and Bulk Operations.

Ready to launch your first pass program?

Create your workspace, configure your pass template, and test a real pass in Apple Wallet and Google Wallet before you scale.