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

Pass Lifecycle & Statuses

Understand Created, Not Installed, Installed, Expired, and Voided pass states and how they interact with billing and scans.

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

Live Wallet registration status popover (Zoomed)

Click the Apple Wallet or Google Wallet badge on any pass row to verify Active registrations, Total registrations, Removals, and registration timestamps.

Overview

Passinstance governs every issued pass through three orthogonal state machines tracked on the Pass model:

  1. 1
    pass status (11 values): Functional business validity state determining whether a pass can be installed, scanned, or redeemed.
  2. 2
    PassLifecycleStatus (5 stages): Administrative retention and revocation progression from ACTIVE to DELETED.
  3. 3
    WalletPropagationStatus (5 stages): Asynchronous cloud synchronization state tracking APNs and Google Wallet push delivery.

System Architecture: Pass Lifecycle & Wallet Propagation State Machines

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
PASS LIFECYCLE STATE MACHINE & WALLET PROPAGATION
STAGE 01
1
BUSINESS STATUS (pass status) [DRAFT] / [AWAITING_OPT_IN] / [PENDING_ACTIVATION]
[GENERATING][ACTIVE] <[INACTIVE] / [SUSPENDED] [REDEEMED] [EXPIRED] [CANCELLED] / [VOIDED]
STAGE 02
2
LIFECYCLE PROGRESSION (PassLifecycleStatus) [ACTIVE][VOIDING][VOIDED][DELETING][DELETED]
STAGE 03
3
CLOUD SYNC PIPELINE (WalletPropagationStatus) [NONE][PENDING][QUEUED][SUCCEEDED] (or [FAILED] + Retry)

1. All 11 pass status Business States

pass status ValueScanner Validation ResultWallet Visual Rendering & Behavior
DRAFTRejected (INVALID)Pass record exists in DB prior to signing; download link is not yet active.
AWAITING_OPT_INRejected (PENDING)Created via PassFlow or campaign; awaiting email/SMS OTP or GDPR consent confirmation.
PENDING_ACTIVATIONRejected (PENDING)Issued pass awaiting external payment capture or POS activation scan.
GENERATINGRejected (PENDING)Cryptographic .pkpass bundle or Google Wallet object is currently being compiled by a worker.
ACTIVEAccepted (SUCCESS)Valid, live pass eligible for scanning, points accrual, NFC tap, and push notifications.
INACTIVERejected (INVALID)Temporarily deactivated by operator (POST /api/v1/batch-pass-operations/deactivate).
SUSPENDEDRejected (INVALID)Frozen due to suspected fraud, payment delinquency, or security hold; reversible to ACTIVE.
REDEEMEDRejected (ALREADY_USED)Single-use coupon or event ticket has been scanned and consumed (VOIDED_AFTER_SCAN scan mode).
EXPIREDRejected (EXPIRED)Current timestamp has passed Pass.expirationDate; barcode greys out on customer device.
CANCELLEDRejected (ALREADY_VOIDED)Enrollment or order was cancelled (e.g., refunded ticket order) prior to redemption.
VOIDEDRejected (ALREADY_VOIDED)Permanently invalidated via Pass Voiding API; sets "voided": true in Apple pass.json and STATE_EXPIRED/INACTIVE in Google Wallet.

2. The 5 PassLifecycleStatus Stages

The lifecycleStatus column coordinates safe multi-step revocation and database cleanup without leaving orphaned wallet objects on user devices:

StageDescription
ACTIVENormal operational state across active, inactive, or expired passes.
VOIDINGTransitional lock acquired when a void request is initiated; enqueues high-priority void push updates to Apple and Google Wallet.
VOIDEDTerminal revocation completed; voidedAt timestamp and voidReason are permanently recorded on the pass ledger.
DELETINGTransitional lock acquired when an operator requests permanent record deletion; revokes download tokens and de-links storage assets.
DELETEDSoft-deleted tombstone state or finalized removal prior to GDPR purge.

3. walletVoidStatus (WalletPropagationStatus), Deletion Modes & Artifacts

Passinstance tracks asynchronous cloud push delivery, deletion semantics, and wallet artifact compilation using dedicated Passinstance database columns and enums on Pass:

walletVoidStatus (WalletPropagationStatus)

Whenever a void/status transition is dispatched to Apple APNs or Google Wallet, Pass.walletVoidStatus tracks delivery progress:

Stage (WalletPropagationStatus)Description
NONEPass has been created, or no void/propagation state has been queued.
PENDINGA field update or lifecycle transition was committed to database and is waiting to be picked up by the propagation dispatcher.
QUEUEDA background job queue wallet sync job is actively queued to transmit the APNs HTTP/2 push or Google Wallet PATCH request.
SUCCEEDEDAll registered devices/cloud objects acknowledged the update (for Apple Wallet, device fetched the latest .pkpass bundle via GET /v1/passes/...).
FAILEDDelivery encountered an upstream error (e.g., unregistered APNs token or Google API quota error); eligible for retry.

PassDeletionMode & ArtifactStatus

  • PassDeletionMode (SOFT | HARD): DELETE /api/v1/passes/:id performs a SOFT delete (setting archivedAt, freeing tenant (customerId, externalId) uniqueness for re-issuance while retaining audit logs), whereas DELETE /api/v1/passes/:id/hard performs a HARD purge.
  • ArtifactStatus (appleArtifactStatus, googleArtifactStatus): NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATED tracks whether each platform's cryptographic package/cloud object is compiled and current.

Important Billing & Wallet Lifecycle Invariant

Important: Voiding or expiring a pass rejects future scanner validations and visually marks the card as invalid/greyed-out in the user's wallet, but Apple iOS and Google Android do not allow third-party servers to forcibly delete a pass from a customer's device without user action. In Apple Wallet, voided passes suppress lock-screen updates unless updateVoidedExpiredPasses: true is enabled on the template. An installed pass continues to count as an active device registration until the customer removes it from their wallet or device deregistration completes.

Pass Deactivation & Voiding API (Passes API / Pass Voiding API)

Passinstance exposes reversible deactivation (POST /api/v1/passes/:id/deactivate) and formal voiding endpoints under /api/v1/passes/voiding (accepting VoidingReason: EXPIRED, CANCELLED, LOST, STOLEN, DUPLICATE, FRAUD, TECHNICAL_ISSUE, CUSTOMER_REQUEST, ADMIN_ACTION, SYSTEM_AUTO, OTHER):

EndpointScopeDescription
POST /api/v1/passes/:id/deactivateSingle PassTemporarily transitions pass status from ACTIVE to INACTIVE.
POST /api/v1/passes/voiding/:id/voidSingle PassVoids (voided: true) or re-activates (voided: false) a single pass (204 No Content).
POST /api/v1/passes/voiding/batch-voidArray of PassesVoids or activates multiple passIds in a single request (request payload).
POST /api/v1/passes/voiding/template-voidEntire TemplateMass-voids all active passes issued under a templateId (request payload).
GET /api/v1/passes/voiding/:id/voiding-historyAudit TrailReturns chronological void/activation events for the pass.

Example: Void a Single Pass (request payload)

POST /api/v1/passes/voiding/pass_01j8k9m2n3p4q5r6/void Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Order refunded via Shopify webhook #SH-99412",
    "sendPushNotification": true,
    "pushNotificationMessage": "This pass has been voided following your order refund.",
    "updateGoogleWallet": true
  }
}

HTTP Status: Returns 204 No Content on success, immediately setting status = "VOIDED", lifecycleStatus = "VOIDED", and updating walletVoidStatus (WalletPropagationStatus: NONE -> PENDING -> QUEUED -> SUCCEEDED) as background wallet pushes run.

Example: Batch-Void Multiple Passes (request payload)

POST /api/v1/passes/voiding/batch-void Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "passIds": [
    "pass_01j8k9m2n3p4q5r6",
    "pass_01j8k9m2n3p4q5r7"
  ],
  "voided": true,
  "options": {
    "reason": "EXPIRED",
    "customReason": "Expired seasonal VIP cohort",
    "sendPushNotification": true
  }
}

Example: Void All Passes for a Template (request payload)

POST /api/v1/passes/voiding/template-void Headers: X-API-Key: <API_KEY> | Content-Type: application/json

JSON
{
  "templateId": "tmpl_01hxyz987654321",
  "voided": true,
  "options": {
    "reason": "CANCELLED",
    "customReason": "Summer 2026 promotional campaign concluded",
    "sendPushNotification": true
  }
}

See Bulk Operations for array-based activation, deactivation, and deletion workflows, or Active Passes & Usage Limits for capacity metering rules.

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.