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
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
activePassespool 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 State | Counts Toward activePasses Quota? | Technical Rationale |
|---|---|---|
| Draft Templates & Previews | No (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
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.
-
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
{
"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:
GET /api/v1/customer/cus_89a12b34-56c7-4d89-9e01-23456789abcd/usage-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"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:
GET /api/v1/organizations/current/billing-summary HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
{
"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 }
]
}
Related Documentation
-
Compare capacity tiers and add-ons in Pricing & Subscription Plans.
-
Upgrade or downgrade your subscription in Plan Changes & Cancellation.
-
Review the technical distinction between passes and device registrations in Pass Issuance & Usage Metrics.
