Présentation
Contrairement aux fournisseurs historiques de portefeuilles numériques qui facturent chaque enregistrement généré en base de données ou chaque lien e-mail non ouvert, Passinstance mesure la capacité d'abonnement strictement sur les passes de portefeuille actifs (activePasses) — des instances de passes en production (pass status.ACTIVE) qui disposent actuellement d'au moins un enregistrement d'appareil joignable dans Apple Wallet (bundleId / passTypeIdentifier) ou Google Wallet.
Vous pouvez suivre votre consommation en temps réel dans le tableau de bord sous Settings -> Billing (/settings/billing/overview), via GET /api/v1/billing/usage et GET /api/v1/customer/:customerId/usage-summary, ou à travers des espaces de travail affiliés via GET /api/v1/organizations/current/billing-summary.
Flux de mesure des quotas en temps réel et d'application des limites
Important : Lorsqu'un détenteur de pass supprime un pass d'Apple Wallet ou de Google Wallet, ou lorsqu'un administrateur révoque/supprime une instance de pass obsolète, la capacité libérée est automatiquement restituée au pool
activePassesde votre espace de travail.
Qu'est-ce qui est comptabilisé dans votre quota de passes actifs ?
Conformément à PASS_ANALYTICS_METRIC_DEFINITIONS (metric-definitions.ts), Passinstance évalue chaque état de pass comme suit :
| État du cycle de vie du pass | Comptabilisé dans le quota activePasses ? | Justification technique |
|---|---|---|
| Modèles brouillons et aperçus | Non (0) | Les aperçus de conception et les brouillons non publiés n'ont aucun enregistrement d'appareil en production. |
Passes créés / non réclamés (unclaimedPasses) | Non (0) | Les passes générés via import CSV, API ou campagne d'e-mailing que le client n'a pas encore enregistrés dans le portefeuille de son téléphone ne consomment aucun quota actif. |
Installés et joignables (activePasses) | Oui (1 par pass) | Instances de passes en production avec >= 1 enregistrement d'appareil actif recevant des mises à jour push APNs ou Google Wallet. |
Désinstallés / retirés (inactivePasses) | Non (0) | Dès que tous les appareils désenregistrent le pass (DELETE /v1/devices/.../registrations/...), le pass passe à l'état inactivePasses et cesse de consommer du quota actif. |
Révoqués ou expirés (voidedPasses, expiredPasses) | Non (0) | Les états de pass terminaux sont exclus de activePasses dans metric-definitions.ts. |
Seuil souple de passes créés vs limite stricte de passes actifs (PASS_LIMIT_REACHED)
Pour protéger la stabilité de l'infrastructure contre les boucles d'API incontrôlées tout en offrant aux équipes marketing une marge généreuse pour les envois d'e-mails à taux de conversion partiel, Passinstance applique une politique à deux niveaux :
-
1
Le seuil souple de 5× sur les passes créés (
activePassLimit × 5) :
- Vous pouvez générer jusqu'à 5 fois votre limite de passes actifs en nombre total d'enregistrements non réclamés (par ex., 1 000 passes créés sur le forfait Starter à 200 actifs, ou 10 000 passes créés sur le forfait Growth à 2 000 actifs). - Lorsque vous approchez de ce seuil souple, une bannière d'avertissement s'affiche dans le tableau de bord pour vous inviter à purger les anciens liens non réclamés ou à passer à un forfait supérieur.
-
2
Limite stricte de passes actifs (
PASS_LIMIT_REACHED) :
- Lorsque votre compteur activePasses en production atteint 100 % de votre effectiveActivePassLimit, les passes installés existants continuent de fonctionner et d'être scannés normalement, mais les nouvelles créations ou activations de passes renvoient une enveloppe d'erreur structurée PASS_LIMIT_REACHED jusqu'à ce que de la capacité soit libérée ou que le forfait soit mis à niveau.
Enveloppe d'erreur standard 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
}
Interrogation de l'utilisation en temps réel et des cumuls de facturation d'organisation
1. Résumé de consommation de l'espace de travail (GET /api/v1/customer/:customerId/usage-summary)
Récupérez les compteurs en temps réel pour les passes actifs, le total des passes créés, les scans mensuels, le stockage de ressources et le volume de notifications push :
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. Cumul de facturation à l'échelle de l'organisation (GET /api/v1/organizations/current/billing-summary)
Pour les agences et les entreprises gérant plusieurs espaces de travail affiliés (production, staging, client-a) sous une même entité 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 }
]
}
Documentation connexe
-
Comparez les paliers de capacité et les options dans Tarification et forfaits d'abonnement.
-
Mettez à niveau ou rétrogradez votre abonnement dans Modifications de forfait et résiliation.
-
Consultez la distinction technique entre les passes et les enregistrements d'appareils dans Métriques d'émission et d'utilisation des passes.
