Overview
Passinstance provides transparent, fixed-capacity subscription tiers metered strictly by Active Wallet Passes—passes currently installed and reachable on customer devices. Powered by Billing API (/api/v1/billing/*) and accessible under Settings -> Billing (/settings/billing/overview, /add-ons, /payment-method, /invoices), workspaces can subscribe in EUR (€) or USD (\$) across BillingFrequency (Monthly, Yearly with ~20% annual savings), attach modular add-ons, and validate promotional discount codes.
Subscription & Add-On Metering Architecture
Important: You can inspect live plan definitions and feature entitlements at any time on /pricing or programmatically via
GET /api/v1/billing/plans. Nonprofits and educational institutions qualify for custom recurring discounts—see Eligibility & Benefits.
Fixed-Capacity Subscription Tiers
| Plan Tier | Active Wallet Pass Capacity | Monthly Billing (EUR / USD) | Annual Billing (~20% Savings) | Target Use Cases & Core Entitlements |
|---|---|---|---|---|
| Free | 5 active passes | €0 / \$0 | Free forever | Sandbox prototyping, visual template design, live Apple/Google device testing, and REST API evaluation. |
| Starter | 200 active passes | €16 / \$22 /mo | ~20% discount | Single-location loyalty programs, boutique clubs, pilot store launches, and web/mobile scanner pairing. |
| Growth | 2,000 active passes | €120 / \$180 /mo | ~20% discount | Multi-location retail loyalty, recurring event series, automated CRM workflows, and Push/Pull webhooks. |
| Scale 10K | 10,000 active passes | €400 / \$700 /mo | ~20% discount | High-volume hospitality chains, regional attractions, custom RBAC roles, and high-throughput API pipelines. |
| Enterprise | 10,001+ active passes | Custom | Custom Agreement | Multi-brand enterprise groups, SAML 2.0 SSO, dedicated SLAs, custom PricingAgreement tiers, and white-label portals. |
Base Subscriptions, Add-Ons & Promotion Codes (Billing API)
Passinstance separates your base subscription plan from modular add-on subscriptions so you can expand specific capabilities (such as custom white-label domains or additional active pass blocks) without jumping to a full enterprise contract.
Core Plan & Add-On API Endpoints & Status Enumerations
Subscription records track status via subscription status (ACTIVE, INACTIVE, EXPIRED, CANCELLED, SUSPENDED, TRIALING, PAST_DUE, GRACE_PERIOD, RESTRICTED, CANCEL_AT_PERIOD_END, UNPAID, ARCHIVED) and billing cycles via BillingFrequency (Monthly, Yearly):
| Endpoint | HTTP Verb | Description |
|---|---|---|
/api/v1/billing/plans | GET | Returns active subscription plans, pricing in EUR/USD, BillingFrequency, and included feature entitlements. |
/api/v1/billing/subscription | GET | Returns the active subscription (subscription status), billing cycle, and currentPeriodEnd. |
/api/v1/billing/overview | GET | Combines base plan, add-on subscriptions, real-time usage meters, and upcoming invoice preview. |
/api/v1/billing/addons | GET | Lists available self-serve add-ons (capacity packs, custom vanity domain add-ons). |
/api/v1/billing/add-on-subscriptions | GET / POST | Lists active add-ons or attaches a recurring add-on subscription (request payload). |
/api/v1/billing/add-on-service-requests | POST | Submits a managed setup request (request payload) for custom white-label DNS or certificate onboarding. |
/api/v1/billing/promotions/validate | POST | Validates a promotional code (request payload) against a target plan and currency. |
Querying Consolidated Billing Overview
GET /api/v1/billing/overview HTTP/1.1
Host: api.passinstance.com
Authorization: Bearer <access_token>
Response Payload (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
}
}
Validating a Promotion Code (POST /api/v1/billing/promotions/validate)
Validate whether a promotional code applies to your selected tier and billing interval using request payload ({ code, planId?, billingInterval?: 'monthly' | 'annual', currency?: 'EUR' | 'USD' }), returning IPromotionEligibilityDecision (plus stackability governed by 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
}
Related Documentation
-
Understand how active pass consumption is metered in Active Passes & Usage Limits.
-
Preview proration and upgrade or cancel plans in Plan Changes & Cancellation.
