Skip to content
Help Center Guide · Pass Templates
3 min readVerified 2026-11-16

Export and Import as JSON

Backup, restore, and transfer pass templates across workspaces using sanitized JSON schemas and security guardrails.

In This Guide

Overview

Passinstance supports exporting and importing complete template definitions as structured, portable JSON files. This capability enables:

  • Environment Migration: Promoting tested pass templates from a sandbox workspace to a production workspace without manual recreation.
  • Backup & Disaster Recovery: Storing canonical template configurations in Git repositories or version control systems (Configuration as Code).
  • Template Sharing & Cloning: Distributing standardized loyalty, ticket, or membership layouts across distinct client accounts or franchise operators.

Exported files use the canonical Passinstance export specification (TEMPLATE_EXPORT_FORMAT = 'passinstance-template', schema version 1) implemented in template-import-export.util.ts. System identifiers, database primary keys, tenant IDs, and cryptographic signing certificates are stripped automatically to guarantee multi-tenant security and prevent identity collisions.

System Architecture: Template Export & Import Workflow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
TEMPLATE EXPORT & IMPORT PIPELINE
STAGE 01 SOURCE WORKSPACE (Sandbox / Testing)
Template with fields, custom properties, colors, barcodes, and relevancy rules
STAGE 02 EXPORT SANITIZATION ENGINE (Template Export Engine)
buildSanitizedTemplateExportPayload
1
Injects envelope: format: 'passinstance-template', version: 1
2
Strips tenant boundaries: customerId, tenantId, id, certificateId
3
Strips Apple credentials: teamIdentifier, passTypeIdentifier
4
Encodes retina image asset references or portable CDN URLs
STAGE 03 PORTABLE JSON ARTIFACT (template-export.json)
Clean, human-readable JSON schema
Independent of database row IDs or tenant secrets
STAGE 04 IMPORT VALIDATION & SECURITY ENGINE
normalizeTemplateImport
1
Size Guard: Enforces maximum upload size limit = 5 * 1024 * 1024 (5 MB max)
2
Prototype Pollution Guard: Strips __proto__, constructor, prototype
3
Reconciles Custom Properties and creates GIN indexes in target database
4
Assigns target workspace certificate and binds local tenant boundary
STAGE 05 DESTINATION WORKSPACE (Production / Live)
New Template created with status: PUBLISHED (or updated DRAFT revision)
Ready for live issuance, PassFlow enrollment, and batch CSV campaigns

The Passinstance Template Export Format Specification

The export generator (buildSanitizedTemplateExportPayload) outputs a standardized JSON envelope conforming to TEMPLATE_EXPORT_SCHEMA_VERSION = 1:

JSON
{
  "format": "passinstance-template",
  "version": 1,
  "exportedAt": "2026-11-16T20:40:00.000Z",
  "template": {
    "name": "Artisan Coffee Club - Gold Tier",
    "kind": "storeCard",
    "organizationName": "Artisan Roasters",
    "description": "Artisan Coffee Loyalty Card",
    "colors": {
      "backgroundColor": "rgb(20, 35, 28)",
      "foregroundColor": "rgb(255, 255, 255)",
      "labelColor": "rgb(167, 243, 208)",
      "stripColor": "rgb(255, 255, 255)"
    },
    "barcode": {
      "format": "PKBarcodeFormatQR",
      "messageEncoding": "UTF_8",
      "altText": "{cardNumber}",
      "addSecurityAnimation": true
    },
    "fields": {
      "headerFields": [
        {
          "key": "tier",
          "label": "TIER",
          "value": "Gold Member",
          "textAlignment": "PKTextAlignmentRight"
        }
      ],
      "primaryFields": [
        {
          "key": "holder",
          "label": "MEMBER",
          "value": "{firstName} {lastName}"
        }
      ],
      "secondaryFields": [
        {
          "key": "balance",
          "label": "POINTS BALANCE",
          "value": "{pointsBalance}",
          "numberStyle": "PKNumberStyleDecimal"
        }
      ],
      "auxiliaryFields": [
        {
          "key": "since",
          "label": "MEMBER SINCE",
          "value": "{memberSince}",
          "dateStyle": "PKDateStyleMedium"
        }
      ],
      "backFields": [
        {
          "key": "terms",
          "label": "TERMS & CONDITIONS",
          "value": "Points are earned on every purchase. Terms subject to change."
        }
      ]
    },
    "locations": [
      {
        "latitude": 52.520008,
        "longitude": 13.404954,
        "maxDistance": 150,
        "relevantText": "Welcome to Artisan Roasters! Scan your card for points."
      }
    ],
    "sharing": {
      "sharingProhibited": false
    }
  }
}

Security & Sanitization Invariants

To maintain strict tenant isolation and protect cryptographic assets, Passinstance enforces five core security invariants during export and import (template-import-export.util.ts:25-34):

1. System Key Stripping

The following keys are strictly stripped from export payloads and rejected during import:

  • Primary and foreign keys: id, customerId, tenantId, baseId, groupId.
  • Revision metadata: versionNumber, version, rowKind, status.
  • Passholder records: passes, activePassesCount.
  • Timestamps: createdAt, updatedAt, archivedAt.
  • Apple Developer identity: teamIdentifier, passTypeIdentifier, certificateId.

2. Payload Size Limits

  • maximum upload size limit = 5 * 1024 * 1024 (5 MB): Payloads exceeding 5 megabytes are rejected immediately with HTTP 413.
  • MAX_ZIP_ENTRY_BYTES = 1 * 1024 * 1024 (1 MB): For zipped packages, individual entries cannot exceed 1 MB.
  • MAX_ZIP_ENTRIES = 250: Prevents zip bomb decompression attacks.
  • MAX_PLIST_DEPTH = 32: Prevents recursive entity expansion.

3. Prototype Pollution Prevention

Any incoming JSON object containing __proto__, constructor, or prototype is flagged and sanitized before object construction.

Exporting a Template (Dashboard & REST API)

In the Dashboard

  1. 1
    Open the template in the Visual Editor.
  2. 2
    Click the More actions (...) menu in the top CommandBar.
  3. 3
    Select Export as JSON.
  4. 4
    The browser downloads <template-slug>-export.json immediately.

Via REST API

GET /api/v1/templates/:templateId/export?format=json
Headers
X-API-Key <API_KEY>
BASH
curl -X GET "https://api.passinstance.com/api/v1/templates/tmpl_01h9x8k7m6n5p4/export?format=json" \
  -H "X-API-Key: <API_KEY>" \
  -o template-export.json

Importing a Template (Dashboard & REST API)

1. Import as a New Template (POST /api/v1/templates/import)

Creates a completely new template in the destination workspace:

BASH
curl -X POST "https://api.passinstance.com/api/v1/templates/import" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d @template-export.json

HTTP Response (201 Created)

JSON
{
  "success": true,
  "data": {
    "id": "tmpl_new_destination_01",
    "name": "Artisan Coffee Club - Gold Tier",
    "kind": "storeCard",
    "status": "PUBLISHED",
    "versionNumber": 1,
    "rowKind": "PRODUCTION",
    "createdAt": "2026-11-16T20:45:00.000Z"
  },
  "statusCode": 201
}

2. Import into an Existing Draft (POST /api/v1/templates/:id/import-draft)

Updates the working DRAFT revision of an existing template without modifying live published passes:

BASH
curl -X POST "https://api.passinstance.com/api/v1/templates/tmpl_existing_01/import-draft" \
  -H "X-API-Key: <API_KEY>" \
  -H "Content-Type: application/json" \
  -d @template-export.json

Troubleshooting Export & Import

Symptom / ErrorRoot CauseResolution
Unrecognized format identifierJSON lacks "format": "passinstance-template" or uses unknown format.Ensure the root JSON includes "format": "passinstance-template" and "version": 1.
Payload exceeds 5MB limitLarge images or binary assets are embedded inside the JSON.Remove raw base64 data and upload images through the asset management endpoint or dashboard UI.
Certificate not assignedExported template does not carry signing certificates.This is intentional. After importing, navigate to Template Settings and bind the target workspace's Apple and Google Wallet credentials.

Next, explore Organize Templates & Passes to manage template catalogs, or read Template Versions & Publishing to promote imported drafts into production.

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.