Skip to content
Helpcentrum-gids · Pakketten & verbruik
3 min leestijdGecontroleerd 2026-11-16

Actieve passen & gebruikslimieten

Lees waarom alleen actieve Wallet-registraties tellen en hoe de ruime 5×-limiet voor aangemaakte records werkt.

In deze gids

Overzicht

In tegenstelling tot traditionele aanbieders van digitale wallets die kosten in rekening brengen voor elk gegenereerd databaserecord of elke ongeopende e-maillink, meet Passinstance de abonnementscapaciteit strikt op basis van actieve wallet-passen (activePasses) — live pasinstanties (pass status.ACTIVE) die momenteel ten minste één bereikbare apparaatregistratie hebben in Apple Wallet (bundleId / passTypeIdentifier) of Google Wallet.

U kunt het realtime verbruik volgen in het Dashboard onder Instellingen -> Facturering (/settings/billing/overview), via GET /api/v1/billing/usage en GET /api/v1/customer/:customerId/usage-summary, of over gekoppelde werkruimten heen via GET /api/v1/organizations/current/billing-summary.

Realtime quotummeting en stroom voor limiethandhaving

SYSTEEMARCHITECTUUR
INTERACTIEVE ARCHITECTUUR
SYSTEEMARCHITECTUURSTROOM: METING VAN ACTIEVE PASSEN & QUOTUMHANDHAVING
FASE 01 PASLEVENSCYCLUS & WALLET-GEBEURTENISSEN
Pas aangemaakt (Concept
/ Niet-geclaimde URL)
Wallet-opslaangebeurt.
(APNs-reg / Google JWT)
Wallet verwijderd /
Server-side ongeldig
[ 0 Actief quotum ] [ +1 activePasses ] [ Maakt quotum vrij ]
FASE 02 QUOTUMDREMPELS & HANDHAVINGSENGINE
Zachte drempel aangemaakte passen: totalPasses <= effectiveActivePassLimit * 5
Toont adviserende waarschuwing in Dashboard (breekt nooit live passen)
Hard plafond actieve passen: activePasses >= effectiveActivePassLimit
Weigert nieuwe uitgiften/activeringen met HTTP 403/429 PASS_LIMIT_REACHED

Belangrijk: Wanneer een pashouder een pas verwijdert uit Apple Wallet of Google Wallet, of wanneer een beheerder een verouderde pasinstantie ongeldig verklaart of verwijdert, wordt de vrijgekomen capaciteit automatisch teruggegeven aan de activePasses-pool van uw werkruimte.

Wat telt mee voor uw quotum van actieve passen?

In overeenstemming met PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts) beoordeelt Passinstance elke passtatus als volgt:

Status in paslevenscyclusTelt mee voor activePasses-quotum?Technische onderbouwing
Conceptsjablonen en voorbeeldenNee (0)Ontwerpvoorbeelden en niet-gepubliceerde concepten hebben geen live apparaatregistraties.
Aangemaakte / niet-geclaimde passen (unclaimedPasses)Nee (0)Passen die zijn gegenereerd via CSV-import, API of e-mailcampagne waarbij de klant de pas nog niet in de telefoonwallet heeft opgeslagen, verbruiken geen actief quotum.
Geïnstalleerd en bereikbaar (activePasses)Ja (1 per pas)Live pasinstanties met >= 1 actieve apparaatregistratie die push-updates van APNs of Google Wallet ontvangen.
Verwijderd (inactivePasses)Nee (0)Zodra alle apparaten de registratie van de pas opheffen (DELETE /v1/devices/.../registrations/...), gaat de pas over naar inactivePasses en verbruikt deze geen actief quotum meer.
Ongeldig verklaard of verlopen (voidedPasses, expiredPasses)Nee (0)Eindstatussen van passen zijn uitgesloten van activePasses in metric-definitions.ts.

Zachte drempel voor aangemaakte passen vs. harde actieve limiet (PASS_LIMIT_REACHED)

Om de stabiliteit van de infrastructuur te beschermen tegen op hol geslagen API-lussen en tegelijkertijd marketingteams ruime marges te bieden voor e-mailverzendingen met gedeeltelijke conversiepercentages, hanteert Passinstance een tweeledig beleid:

  1. 1
    De zachte drempel van 5× aangemaakte passen (activePassLimit × 5):

- U kunt tot 5 keer uw limiet voor actieve passen aan totale niet-geclaimde records genereren (bijv. 1.000 aangemaakte passen in het Starter-abonnement met 200 actieve passen, of 10.000 aangemaakte passen in het Growth-abonnement met 2.000 actieve passen). - Wanneer u deze zachte drempel nadert, verschijnt er een adviserende banner in het dashboard die u vraagt om verouderde niet-geclaimde links op te schonen of uw abonnement te upgraden.

  1. 2
    Harde limiet voor actieve passen (PASS_LIMIT_REACHED):

- Wanneer uw aantal live activePasses 100% van uw effectiveActivePassLimit bereikt, blijven bestaande geïnstalleerde passen normaal functioneren en scannen, maar retourneren nieuwe pasaanmakingen of activeringen een gestructureerde PASS_LIMIT_REACHED-foutenvelop totdat er capaciteit wordt vrijgemaakt of geüpgraded.

Standaard PASS_LIMIT_REACHED-foutenvelop

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
}

Realtime gebruik en factureringsoverzichten op organisatieniveau opvragen

1. Verbruiksoverzicht van de werkruimte (GET /api/v1/customer/:customerId/usage-summary)

Haal realtime meters op voor actieve passen, het totale aantal aangemaakte passen, maandelijkse scans, asset-opslag en het volume aan pushmeldingen:

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. Organisatiebreed factureringsoverzicht (GET /api/v1/organizations/current/billing-summary)

Voor bureaus en ondernemingen die meerdere gekoppelde werkruimten (production, staging, client-a) beheren onder één overkoepelende 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 }
  ]
}

Gerelateerde documentatie

Klaar om uw eerste kaartprogramma te lanceren?

Maak uw workspace aan, configureer uw sjabloon en test een echte kaart in Apple Wallet en Google Wallet voordat u opschaalt.