Overview
Passinstance governs every issued pass through three orthogonal state machines tracked on the Pass model:
-
1
pass status (11 values): Functional business validity state determining whether a pass can be installed, scanned, or redeemed.
-
2
PassLifecycleStatus(5 stages): Administrative retention and revocation progression fromACTIVEtoDELETED. -
3
WalletPropagationStatus(5 stages): Asynchronous cloud synchronization state tracking APNs and Google Wallet push delivery.
System Architecture: Pass Lifecycle & Wallet Propagation State Machines
1. All 11 pass status Business States
| pass status Value | Scanner Validation Result | Wallet Visual Rendering & Behavior |
|---|---|---|
DRAFT | Rejected (INVALID) | Pass record exists in DB prior to signing; download link is not yet active. |
AWAITING_OPT_IN | Rejected (PENDING) | Created via PassFlow or campaign; awaiting email/SMS OTP or GDPR consent confirmation. |
PENDING_ACTIVATION | Rejected (PENDING) | Issued pass awaiting external payment capture or POS activation scan. |
GENERATING | Rejected (PENDING) | Cryptographic .pkpass bundle or Google Wallet object is currently being compiled by a worker. |
ACTIVE | Accepted (SUCCESS) | Valid, live pass eligible for scanning, points accrual, NFC tap, and push notifications. |
INACTIVE | Rejected (INVALID) | Temporarily deactivated by operator (POST /api/v1/batch-pass-operations/deactivate). |
SUSPENDED | Rejected (INVALID) | Frozen due to suspected fraud, payment delinquency, or security hold; reversible to ACTIVE. |
REDEEMED | Rejected (ALREADY_USED) | Single-use coupon or event ticket has been scanned and consumed (VOIDED_AFTER_SCAN scan mode). |
EXPIRED | Rejected (EXPIRED) | Current timestamp has passed Pass.expirationDate; barcode greys out on customer device. |
CANCELLED | Rejected (ALREADY_VOIDED) | Enrollment or order was cancelled (e.g., refunded ticket order) prior to redemption. |
VOIDED | Rejected (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:
| Stage | Description |
|---|---|
ACTIVE | Normal operational state across active, inactive, or expired passes. |
VOIDING | Transitional lock acquired when a void request is initiated; enqueues high-priority void push updates to Apple and Google Wallet. |
VOIDED | Terminal revocation completed; voidedAt timestamp and voidReason are permanently recorded on the pass ledger. |
DELETING | Transitional lock acquired when an operator requests permanent record deletion; revokes download tokens and de-links storage assets. |
DELETED | Soft-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 |
|---|---|
NONE | Pass has been created, or no void/propagation state has been queued. |
PENDING | A field update or lifecycle transition was committed to database and is waiting to be picked up by the propagation dispatcher. |
QUEUED | A background job queue wallet sync job is actively queued to transmit the APNs HTTP/2 push or Google Wallet PATCH request. |
SUCCEEDED | All registered devices/cloud objects acknowledged the update (for Apple Wallet, device fetched the latest .pkpass bundle via GET /v1/passes/...). |
FAILED | Delivery 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/:idperforms aSOFTdelete (settingarchivedAt, freeing tenant(customerId, externalId)uniqueness for re-issuance while retaining audit logs), whereasDELETE /api/v1/passes/:id/hardperforms aHARDpurge. -
ArtifactStatus(appleArtifactStatus,googleArtifactStatus):NOT_GENERATED | GENERATING | READY | FAILED | INVALIDATEDtracks 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: trueis 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):
| Endpoint | Scope | Description |
|---|---|---|
POST /api/v1/passes/:id/deactivate | Single Pass | Temporarily transitions pass status from ACTIVE to INACTIVE. |
POST /api/v1/passes/voiding/:id/void | Single Pass | Voids (voided: true) or re-activates (voided: false) a single pass (204 No Content). |
POST /api/v1/passes/voiding/batch-void | Array of Passes | Voids or activates multiple passIds in a single request (request payload). |
POST /api/v1/passes/voiding/template-void | Entire Template | Mass-voids all active passes issued under a templateId (request payload). |
GET /api/v1/passes/voiding/:id/voiding-history | Audit Trail | Returns 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
{
"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 Contenton success, immediately settingstatus = "VOIDED",lifecycleStatus = "VOIDED", and updatingwalletVoidStatus(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
{
"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
{
"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.
