Skip to content
Help Center Guide · Pass Scanning
4 min readVerified 2026-11-16

Scan History & Results

Audit scan outcomes (VALID, ALREADY_REDEEMED, EXPIRED, VOIDED), staff timestamps, locations, and validation responses.

In This Guide

Overview

Every validation request processed by Passinstance generates an immutable audit record containing the evaluated decision, reasonCode, step-by-step ruleTrace, operator metadata, and pre/post pass balances. You can review scan histories visually in the Dashboard under Scanner (/scanner), inspect individual scan receipts, query idempotent operation outcomes, perform non-mutating pass lookups, or stream full CSV exports for accounting reconciliation.

Important: Read-only lookup routes (GET /api/v1/scans/pass?barcode=... or GET /api/v1/scans/pass/:barcodeValue) allow POS terminals and customer service desks to inspect pass status, externalId, tier, and balance without recording a scan event, incrementing counters, or voiding single-use vouchers.

Architecture & Audit Lookup Flow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
SCAN RECEIPT & AUDIT EXPORT PIPELINE
PARTICIPATING SYSTEM ACTORS
P1 POS / Scanner Client
P2 Scan Validation API (/api/v1/scans)
P3 Validation Config API (/api/v1/validation)
STEP 1 REQUEST / ACTION GET/scans/pass?barcode=...
STEP 2 RESPONSE 200 OK (IPassLookupResponse)
STEP 3 REQUEST / ACTION GET/scans/operations/:idem
STEP 4 RESPONSE 200 OK (Cached ScanResponse)
STEP 5 REQUEST / ACTION GET/scans/result/:scanId
STEP 6 RESPONSE 200 OK (Full ruleTrace)
STEP 7 REQUEST / ACTION GET/validation/scan-results/export/csv
STEP 8 RESPONSE 200 OK (text/csv stream: scan_id, decision, operator, effects)

Scan Lookup, Audit & Export Endpoints

MethodEndpointAuth / GuardDescription
GET/api/v1/scans/passx-scanner-keyRead-only pass lookup via ?barcode=... query parameter (recommended for URL-shaped payloads). Does not create a scan record.
GET/api/v1/scans/pass/:barcodeValuex-scanner-keyRead-only pass lookup by path parameter returning IPassLookupResponse.
GET/api/v1/scans/result/:scanIdx-scanner-keyRetrieves the complete result and ruleTrace of a specific scan by its UUID scanId.
GET/api/v1/scans/operations/:idempotencyKeyx-scanner-keyRetrieves the stored request payload receipt for a previously submitted x-idempotency-key.
GET/api/v1/validation/scansWorkspace JWT / API KeyLists paginated workspace scan logs for the Dashboard (/scanner).
GET/api/v1/validation/scans/:scanIdWorkspace JWT / API KeyFetches a single workspace scan audit record and trace for Dashboard inspection.
GET/api/v1/validation/configs/:id/scans/exportWorkspace JWT / API KeyExports scan history scoped to a specific ScannerConfiguration as CSV.
GET/api/v1/validation/scans/exportWorkspace JWT / API KeyExports workspace-wide scan and redemption logs as CSV.
GET/api/v1/validation/scan-results/export/csvWorkspace JWT / API KeyStreams the full scan audit trail including rule evaluation outcomes (text/csv).

Decision Outcomes (request payload) vs. Persisted scan status

The API returns a high-level decision enum (SUCCESS | FAILED | ALREADY_USED | ALREADY_VOIDED | EXPIRED | INVALID | PENDING) in request payload, while persisting the granular scan status (SUCCESS | FAILED | PENDING | INVALID | EXPIRED | ALREADY_USED | ALREADY_VOIDED | CHECK_IN_SUCCESS | CHECK_OUT_SUCCESS | ALREADY_CHECKED_IN | ALREADY_CHECKED_OUT) on the underlying scan record:

Decision (request payload)StatusTypical reasonCodeRecommended Staff / POS Action
SUCCESSACCEPTEDRULE_ACCEPTEDGrant entry (CHECK_IN_SUCCESS / CHECK_OUT_SUCCESS), apply discount, or confirm balance deduction.
ALREADY_VOIDEDREJECTEDPASS_VOIDED_AFTER_SCANDeny redemption; pass was already consumed in a prior single-use scan.
ALREADY_USEDREJECTEDONCE_PER_DAY_LIMIT_REACHEDInform passholder that their daily or check-in (ALREADY_CHECKED_IN / ALREADY_CHECKED_OUT) allowance has been used.
EXPIREDREJECTEDPASS_EXPIREDDirect customer to renew their membership or claim an active campaign offer.
FAILEDREJECTEDOUT_OF_BALANCE / GEOFENCE_MISMATCHCheck ruleTrace details (e.g., insufficient prepaid balance or wrong checkpoint).
INVALIDREJECTEDPASS_NOT_FOUND / INVALID_NONCEBarcode does not belong to this workspace/template or anti-replay nonce expired.
PENDINGPENDINGOPERATOR_INPUT_REQUIREDPrompt cashier to complete required fields in scanForm (such as transaction amount).

Inspecting a Completed Scan (GET /api/v1/scans/result/:scanId)

JSON
{
  "scanId": "scan_01hxyz7712ab",
  "idempotencyKey": "idem_reg04_20261116_0091",
  "timestamp": "2026-11-16T09:42:11.000Z",
  "decision": "ALREADY_USED",
  "status": "REJECTED",
  "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
  "ruleTrace": [
    { "rule": "PassStatusRule", "passed": true, "durationMs": 1 },
    { "rule": "ExpirationRule", "passed": true, "durationMs": 1 },
    {
      "rule": "OncePerDayRule",
      "passed": false,
      "reasonCode": "ONCE_PER_DAY_LIMIT_REACHED",
      "lastScanAt": "2026-11-16T06:15:04.000Z",
      "durationMs": 3
    }
  ],
  "passSnapshot": {
    "id": "pass_gym_8821",
    "templateId": "tmpl_gym_member",
    "serialNumber": "PI-GYM-8821",
    "externalId": "crm_member_8821",
    "status": "ACTIVE"
  }
}

Non-Mutating Pass Lookup (GET /api/v1/scans/pass)

Before submitting a mutating scan or POS debit, a terminal can query the current state of a pass via GET /api/v1/scans/pass?barcode=PI-GFT-550192 (prefer ?barcode= over the path param whenever barcodes contain slashes or URLs):

GET /api/v1/scans/pass?barcode=PI-GFT-550192
Header
x-scanner-key sk_live_7d9a2f4b8c1e6039a5d2e8f1
JSON
{
  "passId": "pass_gft_550192",
  "templateId": "tmpl_giftcard_eur",
  "templateName": "Retail Gift Card",
  "serialNumber": "PI-GFT-550192",
  "externalId": "shopify_cust_550192",
  "status": "ACTIVE",
  "storedValue": "75.00",
  "expirationDate": "2027-12-31T23:59:59.000Z",
  "isExpired": false,
  "isVoided": false,
  "barcodeValue": "PI-GFT-550192",
  "attributes": {
    "holderName": "Elena Rostova"
  },
  "checkedAt": "2026-11-16T10:15:00.000Z"
}

Exporting Scan Logs to CSV

For shift reconciliation, finance audits, or BI ingestion, export scan histories directly as UTF-8 CSV streams (Content-Type: text/csv; charset=utf-8):

  • Single Configuration Export: GET /api/v1/validation/configs/:id/scans/export?from=2026-11-01&to=2026-11-16
  • All Configurations Export: GET /api/v1/validation/scans/export?templateId=tmpl_loyalty_01
  • Full Audit Results Export: GET /api/v1/validation/scan-results/export/csv

See Scanning & Redemption Reports and Data Exports & Reporting for analytics aggregation options.

Related Product & Developer Documentation

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.