Skip to content
Help Center Guide · Plans & Usage
3 min readVerified 2026-11-16

Active Passes & Usage Limits

Learn why Passinstance bills strictly on Active Wallet Registrations (not created passes) and how the 5x created-pass soft threshold works.

In This Guide

Overview

Unlike legacy digital wallet providers that bill for every generated database record or unopened email link, Passinstance meters subscription capacity strictly on Active Wallet Passes (activePasses)—live pass instances (pass status.ACTIVE) that currently have at least one reachable device registration in Apple Wallet (bundleId / passTypeIdentifier) or Google Wallet.

You can monitor real-time consumption in the Dashboard under Settings -> Billing (/settings/billing/overview), via GET /api/v1/billing/usage and GET /api/v1/customer/:customerId/usage-summary, or across sibling workspaces via GET /api/v1/organizations/current/billing-summary.

Real-Time Quota Metering & Limit Enforcement Flow

SYSTEM ARCHITECTURE FLOW
INTERACTIVE ARCHITECTURE
ACTIVE PASS METERING & QUOTA ENFORCEMENT
STAGE 01 PASS LIFECYCLE & WALLET EVENTS
Pass Created (Draft /
Unclaimed Download URL)
Wallet Save Event
(APNs Reg / Google JWT)
Wallet Uninstall /
Server-Side Void
[ 0 Active Quota ] [ +1 activePasses ] [ Frees Active Quota ]
STAGE 02 QUOTA THRESHOLDS & ENFORCEMENT ENGINE
Soft Created-Pass Threshold: totalPasses <= effectiveActivePassLimit * 5
Emits Advisory Warning in Dashboard (Never Breaks Live Installed Passes)
Hard Active Pass Ceiling: activePasses >= effectiveActivePassLimit
Rejects New Issuances/Activations with HTTP 403/429 PASS_LIMIT_REACHED

Important: When a passholder deletes a pass from Apple Wallet or Google Wallet, or when an administrator voids/deletes an obsolete pass instance, the freed capacity is returned to your workspace's activePasses pool automatically.

What Counts Toward Your Active Pass Quota?

In accordance with PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), Passinstance evaluates each pass state as follows:

Pass Lifecycle StateCounts Toward activePasses Quota?Technical Rationale
Draft Templates & PreviewsNo (0)Design previews and unpublished drafts have no live device registrations.
Created / Unclaimed Passes (unclaimedPasses)No (0)Passes generated via CSV import, API, or email campaign where the customer has not yet saved the pass to their phone wallet do not consume active quota.
Installed & Reachable (activePasses)Yes (1 per pass)Live pass instances with >= 1 active device registration receiving APNs or Google Wallet push updates.
Uninstalled / Removed (inactivePasses)No (0)Once all devices unregister the pass (DELETE /v1/devices/.../registrations/...), the pass transitions to inactivePasses and stops consuming active quota.
Voided or Expired (voidedPasses, expiredPasses)No (0)Terminal pass states are excluded from activePasses in metric-definitions.ts.

Soft Created-Pass Threshold vs. Hard Active Limit (PASS_LIMIT_REACHED)

To protect infrastructure stability against runaway API loops while giving marketing teams generous room for email sendouts with partial conversion rates, Passinstance enforces a two-tier policy:

  1. 1
    The 5× Created-Pass Soft Threshold (activePassLimit × 5):

- You can generate up to 5 times your active pass limit in total unclaimed records (e.g., 1,000 created passes on the Starter 200-active plan, or 10,000 created passes on the Growth 2,000-active plan). - Approaching this soft threshold surfaces an advisory banner in the dashboard prompting you to purge stale unclaimed links or upgrade your plan.

  1. 2
    Hard Active Pass Limit (PASS_LIMIT_REACHED):

- When your live activePasses count reaches 100% of your effectiveActivePassLimit, existing installed passes continue to function and scan normally, but new pass creations or activations return a structured PASS_LIMIT_REACHED error envelope until capacity is freed or upgraded.

Standard PASS_LIMIT_REACHED Error Envelope

JSON
{
  "success": false,
  "error": "FORBIDDEN",
  "messageKey": "api.errors.passLimitReached",
  "message": "Workspace active pass limit reached. Please upgrade your subscription plan or archive inactive passes.",
  "statusCode": 403,
  "timestamp": "2026-11-15T23:35:40.000Z",
  "path": "/api/v1/passes",
  "requestId": "req_9c410e2a",
  "code": "LIMIT_EXCEEDED",
  "errorCode": "PASS_LIMIT_REACHED",
  "activePasses": 200,
  "limit": 200,
  "upgradeRequired": true
}

Querying Real-Time Usage & Organization Billing Rollups

1. Workspace Consumption Summary (GET /api/v1/customer/:customerId/usage-summary)

Retrieve real-time meters for active passes, total created passes, monthly scans, asset storage, and push notification volume:

HTTP
GET /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/usage-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "customerId": "cus_89a12b34-56c7-4d89-9e01-23456789abcd",
  "planId": "growth_monthly",
  "meters": {
    "activePasses": {
      "used": 1420,
      "limit": 2000,
      "remaining": 580,
      "utilizationPercent": 71.0
    },
    "createdPassesSoftLimit": {
      "used": 3890,
      "softLimit": 10000,
      "warningActive": false
    },
    "scansThisPeriod": {
      "count": 14820
    },
    "pushNotificationsThisPeriod": {
      "count": 18420
    },
    "storageBytes": {
      "used": 148902400,
      "limit": 5368709120
    }
  }
}

2. Organization-Wide Billing Rollup (GET /api/v1/organizations/current/billing-summary)

For agencies and enterprises managing multiple sibling workspaces (production, staging, client-a) under one umbrella Organization:

HTTP
GET /api/v1/organizations/current/billing-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
JSON
{
  "organizationId": "org_01933001-2233-7a00-8b11-001122334455",
  "organizationName": "Phenix Group Holdings",
  "totalWorkspaces": 3,
  "aggregatedActivePasses": 4810,
  "aggregatedEffectiveLimit": 12200,
  "workspaces": [
    { "customerId": "cus_89a12b34", "name": "Phenix Flagship (Prod)", "plan": "scale_10k", "activePasses": 3380, "limit": 10000 },
    { "customerId": "cus_77b21c45", "name": "Phenix Boutique", "plan": "growth", "activePasses": 1425, "limit": 2000 },
    { "customerId": "cus_66c32d56", "name": "Phenix Sandbox", "plan": "starter", "activePasses": 5, "limit": 200 }
  ]
}

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.