Übersicht
Im Gegensatz zu herkömmlichen Anbietern digitaler Wallets, die jeden generierten Datenbankeintrag oder ungeöffneten E-Mail-Link berechnen, misst Passinstance die Abonnementkapazität ausschließlich anhand aktiver Wallet-Karten (activePasses) – also aktiver Karteninstanzen (pass status.ACTIVE), die derzeit über mindestens eine erreichbare Geräteregistrierung in Apple Wallet (bundleId / passTypeIdentifier) oder Google Wallet verfügen.
Sie können die Auslastung in Echtzeit im Dashboard unter Einstellungen -> Abrechnung (/settings/billing/overview), über GET /api/v1/billing/usage und GET /api/v1/customer/:customerId/usage-summary oder workspace-übergreifend über GET /api/v1/organizations/current/billing-summary überwachen.
Echtzeit-Kontingentmessung & Ablauf der Limitdurchsetzung
Wichtig: Wenn ein Karteninhaber eine Karte aus Apple Wallet oder Google Wallet löscht oder wenn ein Administrator eine veraltete Karteninstanz entwertet bzw. löscht, wird die freigewordene Kapazität automatisch an den
activePasses-Pool Ihres Workspaces zurückgegeben.
Was zählt zu Ihrem Kontingent für aktive Karten?
Gemäß PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts) bewertet Passinstance jeden Kartenstatus wie folgt:
| Status im Kartenlebenszyklus | Zählt zum activePasses-Kontingent? | Technische Begründung |
|---|---|---|
| Entwurfsvorlagen & Vorschauen | Nein (0) | Designvorschauen und unveröffentlichte Entwürfe haben keine aktiven Geräteregistrierungen. |
Erstellte / Nicht abgerufene Karten (unclaimedPasses) | Nein (0) | Karten, die per CSV-Import, API oder E-Mail-Kampagne generiert wurden, aber vom Kunden noch nicht in der Wallet auf dem Smartphone gespeichert wurden, verbrauchen kein aktives Kontingent. |
Installiert & erreichbar (activePasses) | Ja (1 pro Karte) | Aktive Karteninstanzen mit >= 1 aktiven Geräteregistrierungen, die APNs- oder Google-Wallet-Push-Updates empfangen. |
Deinstalliert / Entfernt (inactivePasses) | Nein (0) | Sobald alle Geräte die Registrierung der Karte aufheben (DELETE /v1/devices/.../registrations/...), wechselt die Karte zu inactivePasses und verbraucht kein aktives Kontingent mehr. |
Entwertet oder abgelaufen (voidedPasses, expiredPasses) | Nein (0) | Endgültige Kartenstatus sind in metric-definitions.ts von activePasses ausgeschlossen. |
Soft-Schwellenwert für erstellte Karten vs. hartes Limit für aktive Karten (PASS_LIMIT_REACHED)
Um die Infrastrukturstabilität vor fehlerhaften API-Endlosschleifen zu schützen und Marketingteams gleichzeitig großzügigen Spielraum für E-Mail-Aussendungen mit teilweisen Konversionsraten zu bieten, setzt Passinstance eine zweistufige Richtlinie durch:
-
1
Der 5× Soft-Schwellenwert für erstellte Karten (
activePassLimit × 5):
- Sie können insgesamt bis zum 5-Fachen Ihres Limits für aktive Karten an nicht abgerufenen Datensätzen generieren (z. B. 1.000 erstellte Karten im Starter-Tarif mit 200 aktiven Karten oder 10.000 erstellte Karten im Growth-Tarif mit 2.000 aktiven Karten). - Wenn Sie sich diesem Soft-Schwellenwert nähern, wird im Dashboard ein Hinweisbanner eingeblendet, das Sie auffordert, veraltete, nicht abgerufene Links zu bereinigen oder Ihren Tarif hochzustufen.
-
2
Hartes Limit für aktive Karten (
PASS_LIMIT_REACHED):
- Wenn Ihr aktueller Zähler activePasses 100 % Ihres effectiveActivePassLimit erreicht, funktionieren und scannen bereits installierte Karten normal weiter, aber neue Kartenerstellungen oder Aktivierungen geben eine strukturierte PASS_LIMIT_REACHED-Fehlermeldung zurück, bis Kapazität freigegeben oder ein Upgrade durchgeführt wird.
Standard-Fehlerstruktur für PASS_LIMIT_REACHED
{
"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
}
Abfragen der Echtzeitnutzung & organisationsweiten Abrechnungsübersichten
1. Zusammenfassung der Workspace-Auslastung (GET /api/v1/customer/:customerId/usage-summary)
Rufen Sie Echtzeitzähler für aktive Karten, insgesamt erstellte Karten, monatliche Scans, Asset-Speicherplatz und das Push-Benachrichtigungsvolumen ab:
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. Organisationsweite Abrechnungszusammenfassung (GET /api/v1/organizations/current/billing-summary)
Für Agenturen und Unternehmen, die mehrere parallele Workspaces (production, staging, client-a) unter einer übergeordneten Organization verwalten:
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 }
]
}
Weiterführende Dokumentation
-
Vergleichen Sie Kapazitätsstufen und Add-ons unter Preise & Abonnementpläne.
-
Stufen Sie Ihr Abonnement hoch oder herab unter Tarifwechsel & Kündigung.
-
Prüfen Sie die technische Unterscheidung zwischen Karten und Geräteregistrierungen unter Kartenausgabe- & Nutzungsmetriken.
