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

Scanning & Redemption Reports

Review check-in throughput by Validation Place, mechanic redemption ledger totals, and repeat customer scan cadence.

In This Guide

Overview

Every barcode scan or contactless NFC tap processed through the Mobile Scanner App, Web Scanner, POS Integration (POST /v1/pos/redeem and POST /v1/pos/scan), Hardware Reader Orchestration (POST /api/v1/reader/redeem), or Scanner Runtime API (POST /api/v1/scans) generates an immutable, cryptographically traceable audit record. Scanning & Redemption Reports (/scanner in the Dashboard and /api/v1/validation/scans) aggregate these events across scanner configurations, physical validation places, operator IDs, and mechanic ledgers to give operations managers complete floor visibility.

Scan Telemetry & Rules Trace Pipeline

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SCAN VALIDATION & REDEMPTION TELEMETRY
STAGE 01 SCANNER & POS INGESTION CHANNELS
Mobile / Web Scanner
POST/api/v1/scans
Retail POS Terminal
POST/v1/pos/redeem
Hardware NFC Reader
`/api/v1/reader/redeem
STAGE 02 14-RULE BUSINESS VALIDATION ENGINE
1
Core Rules: PassStatusRuleExpirationRuleTimeWindowRule
GeofencingRule
2
Mechanic Rules: OncePerDayRuleStampCardAddRulePrepaidCardRule
LoyaltyProgramRuleTierEvaluationRule
3
Security Rules: RateLimitRuleAntiReplayRule (scan nonce)
STAGE 03 SCAN ANALYTICS & LEDGER REPORTING STORE
scan status Breakdown
(SUCCESS, EXPIRED, CHECK_IN_SUCCESS...)
Dimensional Slicing
(scannerConfigId, operatorId, Place)
Stored-Value &
Points Delta
Ledger Rollups

Important: Every scan response records a complete ruleTrace array alongside operatorId, terminalId, scannerConfigurationId, externalId, and GPS location coordinates—allowing compliance teams to audit exactly why a scan was accepted or rejected.

Scan Metric Definitions, scan status & PosOperation Breakdown

Passinstance categorizes validation traffic into canonical KPI buckets defined in PASS_ANALYTICS_METRIC_DEFINITIONS, backed by decision in the scan response and Passinstance database scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT):

Metric KeyUnderlying decision / scan statusOperational Meaning
totalScansAll scan eventsTotal barcode or NFC presentations received by the validation engine within the reporting period.
successfulScansdecision: 'SUCCESS' (SUCCESS, CHECK_IN_SUCCESS, CHECK_OUT_SUCCESS)Scans that passed all 14 validation rules and executed their configured attendance or mechanic action (scan action).
duplicateScansdecision: 'ALREADY_USED' or 'ALREADY_VOIDED' (ALREADY_CHECKED_IN, ALREADY_CHECKED_OUT)Replay attempts on single-use coupons (VOIDED_AFTER_SCAN scan mode) or passes already checked in/out.
expiredScansdecision: 'EXPIRED' (EXPIRED)Presentations of passes whose expirationDate has elapsed.
rejectedScansdecision: 'INVALID' (INVALID)Unrecognized barcode payloads, cross-tenant serial mismatches, or invalid cryptographic NFC signatures.
failedScansdecision: 'FAILED' (FAILED: e.g., OUT_OF_BALANCE, COOLDOWN_ACTIVE)Valid passes rejected by a business rule violation such as insufficient prepaid balance, geofence mismatch, or OncePerDayRule cooldown.

For integrated retail registers hitting POST /v1/pos/redeem, transactions also record PosOperation (DISCOUNT | ADD_POINTS | DEDUCT_VALUE | ADD_STAMPS | VOID | CUSTOM) and walletPropagation (PosWalletPropagationStatus: QUEUED | SKIPPED), inspectable via GET /v1/pos/admin/logs.

Dimensional Reporting: Places, Configurations, and Operators

Validation reports can be filtered and grouped across five operational dimensions:

  1. 1
    Scanner Configuration (scannerConfigurationId): Compare throughput across distinct profiles (e.g., VIP Gate Check-In using CHECK_IN scan mode vs. Cafe Cashier Stamp Add using StampCardAddRule).
  2. 2
    Validation Place & Geofence: Group redemptions by store branch, venue entrance, or GPS coordinate radius to measure foot traffic per physical site.
  3. 3
    Operator & Terminal (operatorId, terminalId): Audit scan volume and manual amount entries per cashier, device name (deviceName), or POS register.
  4. 4
    Channel & Protocol (channel, protocol): Track optical scans (QR, PDF417, CODE128, AZTEC) versus contactless tap presentations (NFC via VAS, SMART_TAP, NDEF, or JWT).
  5. 5
    Stored-Value & Loyalty Ledger Effects (effects): Reconcile total stampsAdded, net pointsDelta, and financial transactionAmount credits/debits by currency (ISO-4217).

Inspecting Scan Audit Logs & Ledger Effects via API

Recorded Scan Event & Ledger Payload Schema

When querying scan history (GET /api/v1/validation/configs/:id/scans or GET /api/v1/scans/result/:scanId), each event provides full diagnostic and financial context:

HTTP
GET /api/v1/scans/result/scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c HTTP/1.1
Host: api.passinstance.com
x-scanner-key: <scanner_api_key>

Response Payload (200 OK)

JSON
{
  "scanId": "scn_019331f4-8e2a-7b00-9c11-44a8e2019b3c",
  "timestamp": "2026-11-16T08:42:11.304Z",
  "decision": "SUCCESS",
  "status": "ACCEPTED",
  "reasonCode": null,
  "channel": "NFC",
  "protocol": "VAS",
  "resolvedConfigId": "cfg_7d82a100-3c4b-4e12-9a88-112233445566",
  "passSnapshot": {
    "id": "pas_55a19c88-102b-4f33-8d99-ccddff001122",
    "templateId": "b4f29c10-83e1-4a7b-9d12-56e8012a9c04",
    "serialNumber": "PI-2026-994812",
    "externalId": "CRM-88210",
    "status": "ACTIVE",
    "tier": "GOLD"
  },
  "effects": {
    "oldBalance": "45.00",
    "newBalance": "32.50",
    "transactionAmount": 12.50,
    "currency": "EUR",
    "amountBalanceBehavior": "ADD_VALUE",
    "pointsDelta": 125,
    "stampsAdded": 0
  },
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true },
    { "rule": "ExpirationRule", "passed": true },
    { "rule": "PrepaidCardRule", "passed": true, "deducted": 12.50 },
    { "rule": "LoyaltyProgramRule", "passed": true, "awardedPoints": 125 }
  ]
}

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.