Panoramica
Passinstance offre fasce di abbonamento trasparenti a capacità fissa, misurate rigorosamente sui Pass attivi nel wallet, ovvero i pass attualmente installati e raggiungibili sui dispositivi dei clienti. Grazie a Billing API (/api/v1/billing/*) e alla sezione Impostazioni -> Fatturazione (/settings/billing/overview, /add-ons, /payment-method, /invoices), i workspace possono sottoscrivere un abbonamento in EUR (€) o USD (\$) con diverse frequenze BillingFrequency (Monthly, Yearly con un risparmio annuale di circa il 20%), associare componenti aggiuntivi modulari e convalidare codici sconto promozionali.
Architettura di misurazione degli abbonamenti e dei componenti aggiuntivi
Importante: Può consultare in qualsiasi momento le definizioni aggiornate dei piani e le funzionalità incluse nella pagina /pricing o a livello programmatico tramite
GET /api/v1/billing/plans. Gli enti non-profit e le istituzioni educative hanno diritto a sconti ricorrenti personalizzati: consulti Idoneità e vantaggi.
Fasce di abbonamento a capacità fissa
| Fascia del piano | Capacità di pass attivi nel wallet | Fatturazione mensile (EUR / USD) | Fatturazione annuale (~20% di risparmio) | Casi d'uso di riferimento e funzionalità principali incluse |
|---|---|---|---|---|
| Free | 5 pass attivi | €0 / \$0 | Gratuito per sempre | Prototipazione in sandbox, progettazione visiva dei modelli, test dal vivo su dispositivi Apple/Google e valutazione delle API REST. |
| Starter | 200 pass attivi | €16 / \$22 /mese | ~20% di sconto | Programmi fedeltà per singolo punto vendita, club boutique, lanci pilota in negozio e associazione dello scanner web/mobile. |
| Growth | 2.000 pass attivi | €120 / \$180 /mese | ~20% di sconto | Programmi fedeltà retail multi-sede, serie di eventi ricorrenti, flussi di lavoro CRM automatizzati e webhook Push/Pull. |
| Scale 10K | 10.000 pass attivi | €400 / \$700 /mese | ~20% di sconto | Catene dell'ospitalità ad alto volume, attrazioni regionali, ruoli RBAC personalizzati e pipeline API ad alta capacità. |
| Enterprise | 10.001+ pass attivi | Su misura | Contratto personalizzato | Gruppi aziendali multi-brand, SSO SAML 2.0, SLA dedicati, fasce PricingAgreement personalizzate e portali white-label. |
Abbonamenti base, componenti aggiuntivi e codici promozionali (Billing API)
Passinstance separa il piano di abbonamento base dagli abbonamenti ai componenti aggiuntivi modulari, in modo da consentirLe di espandere funzionalità specifiche (come i domini personalizzati white-label o blocchi aggiuntivi di pass attivi) senza dover passare a un contratto enterprise completo.
Endpoint API principali per piani e add-on ed enumerazioni di stato
I record Subscription tracciano lo stato tramite subscription status (ACTIVE, INACTIVE, EXPIRED, CANCELLED, SUSPENDED, TRIALING, PAST_DUE, GRACE_PERIOD, RESTRICTED, CANCEL_AT_PERIOD_END, UNPAID, ARCHIVED) e i cicli di fatturazione tramite BillingFrequency (Monthly, Yearly):
| Endpoint | Verbo HTTP | Descrizione |
|---|---|---|
/api/v1/billing/plans | GET | Restituisce i piani di abbonamento attivi, i prezzi in EUR/USD, la BillingFrequency e le abilitazioni funzionali incluse. |
/api/v1/billing/subscription | GET | Restituisce l'abbonamento attivo (subscription status), il ciclo di fatturazione e currentPeriodEnd. |
/api/v1/billing/overview | GET | Combina il piano base, gli abbonamenti agli add-on, i contatori di utilizzo in tempo reale e l'anteprima della prossima fattura. |
/api/v1/billing/addons | GET | Elenca i componenti aggiuntivi self-service disponibili (pacchetti di capacità, add-on per domini vanity personalizzati). |
/api/v1/billing/add-on-subscriptions | GET / POST | Elenca gli add-on attivi o associa un abbonamento ricorrente a un componente aggiuntivo (request payload). |
/api/v1/billing/add-on-service-requests | POST | Invia una richiesta di configurazione gestita (request payload) per l'onboarding di DNS white-label personalizzati o certificati. |
/api/v1/billing/promotions/validate | POST | Convalida un codice promozionale (request payload) rispetto a un piano e a una valuta di destinazione. |
Interrogazione della panoramica consolidata di fatturazione
GET /api/v1/billing/overview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Payload di risposta (200 OK)
{
"subscription": {
"id": "sub_019331b2-7e10-7a44-9b00-112233445566",
"planId": "growth_yearly",
"planName": "Growth",
"status": "ACTIVE",
"interval": "Yearly",
"currency": "EUR",
"unitAmount": 115200,
"currentPeriodStart": "2026-01-15T00:00:00.000Z",
"currentPeriodEnd": "2027-01-15T00:00:00.000Z",
"cancelAtPeriodEnd": false
},
"addOnSubscriptions": [
{
"id": "addsub_019331c0-1122-7d33-8f44-556677889900",
"addonKey": "white_label_domain",
"name": "Custom Vanity Domain & Branded Email",
"status": "ACTIVE",
"unitAmount": 2900,
"interval": "Monthly"
}
],
"capacity": {
"baseActivePassLimit": 2000,
"addOnActivePassLimit": 0,
"effectiveActivePassLimit": 2000,
"currentActivePasses": 1420,
"utilizationPercentage": 71.0
}
}
Convalida di un codice promozionale (POST /api/v1/billing/promotions/validate)
Verifichi se un codice promozionale è applicabile alla fascia e all'intervallo di fatturazione selezionati utilizzando request payload ({ code, planId?, billingInterval?: 'monthly' | 'annual', currency?: 'EUR' | 'USD' }), che restituisce IPromotionEligibilityDecision (oltre alla cumulabilità regolata da promotion policy: PRESERVE | FORFEIT | PRORATE):
POST /api/v1/billing/promotions/validate HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Content-Type: application/json
{
"code": "LAUNCH2026",
"planId": "growth_monthly",
"billingInterval": "monthly",
"currency": "EUR"
}
{
"isEligible": true,
"promotionId": "promo_019331ff-2b30-7c11-9a00-112233445566",
"promotionName": "2026 Launch Offer",
"publicLabel": "25% off first 6 months",
"code": "LAUNCH2026",
"discountType": "PERCENTAGE",
"discountPercent": 25,
"durationType": "REPEATING",
"durationMonths": 6
}
Documentazione correlata
-
Scopra come viene misurato il consumo dei pass attivi in Pass attivi e limiti di utilizzo.
-
Visualizzi l'anteprima del conguaglio proporzionale ed effettui l'upgrade o la cancellazione dei piani in Modifiche al piano e cancellazione.
