Skip to content
Hilfecenter-Anleitung · Tarife & Nutzung
3 Min. LesezeitGeprüft 2026-11-16

Aktive Pässe & Nutzungslimits

Erfahren Sie, warum nur aktive Wallet-Registrierungen zählen und wie das weiche 5×-Limit für erstellte Pässe funktioniert.

In dieser Anleitung

Ü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

SYSTEMARCHITEKTUR-ABLAUF
INTERAKTIVE ARCHITEKTUR
MESSUNG AKTIVER KARTEN & KONTINGENTDURCHSETZUNG
STUFE 01 KARTENLEBENSZYKLUS & WALLET-EREIGNISSE
Karte erstellt (Entwurf
/ Nicht abgerufene URL)
Wallet-Speicherereignis
(APNs-Reg / Google JWT)
Wallet-Entfernung /
Serverseitiger Void
[ 0 Aktives Kontingent ] [ +1 activePasses ] [ Gibt Kontingent frei ]
STUFE 02 KONTINGENTSCHWELLEN & DURCHSETZUNGS-ENGINE
Soft-Schwelle erstellte Karten: totalPasses <= effectiveActivePassLimit * 5
Zeigt Hinweiswarnung im Dashboard (beeinträchtigt nie installierte Karten)
Harte Obergrenze aktive Karten: activePasses >= effectiveActivePassLimit
Lehnt Neuausstellungen/Aktivierungen mit HTTP 403/429 PASS_LIMIT_REACHED ab

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 KartenlebenszyklusZählt zum activePasses-Kontingent?Technische Begründung
Entwurfsvorlagen & VorschauenNein (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. 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.

  1. 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

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
}

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:

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. 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:

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 }
  ]
}

Weiterführende Dokumentation

Bereit für Ihr erstes Wallet-Kartenprogramm?

Erstellen Sie Ihren Workspace, konfigurieren Sie Ihre Vorlage und testen Sie eine echte Karte in Apple Wallet und Google Wallet, bevor Sie skalieren.