Billing & Subscription Overview

EaseLab operates on a software-as-a-service subscription model. Laboratories pay for platform access, feature tiers, and usage limits separately from patient billing (invoices for tests) managed in the tenant portal.

Two billing contexts

flowchart TB
    subgraph SaaS["Lab → EaseLab (SaaS)"]
        PLAN[Subscription plan]
        PAY[Payment gateway]
        SUB[Subscription status]
    end
    subgraph Patient["Lab → Patient"]
        INV[Invoices]
        RCPT[Receipts]
        REF[Referrals]
    end
    PLAN --> SUB
    SUB -->|locked| RO[Read-only mode]
    INV --> RCPT

Context	Where managed	Purpose
SaaS subscription	/billing/*, /admin/subscription	Platform access
Patient invoices	/invoices	Clinical services revenue

This section documents SaaS billing only.

Subscription routes

Route	Screen
/billing/plans	Compare and select plans
/billing/checkout/:planId	Payment checkout
/billing/history	Past payments and invoices
/billing/return	Payment provider return handler
/admin/subscription	Usage and limits dashboard

Tenant payment states

Status	Meaning
Trial	Free evaluation period
Current	Active paid subscription
Overdue	Period ended, grace may apply
Unpaid	Trial ended without conversion
Cancelled	Churned account

Platform admins can also lock tenants from the admin portal.

Trial and conversion

stateDiagram-v2
    [*] --> Trial: Registration
    Trial --> Current: Subscribe / activate plan
    Trial --> Unpaid: Trial expires
    Current --> Overdue: Renewal fails
    Overdue --> Current: Payment success
    Unpaid --> Current: Subscribe
    Current --> Cancelled: Cancel

When trial expires without subscription:

• IsLocked = true
• Read-only mode engages
• Billing routes remain accessible for checkout

Plan tiers

Plans define feature flags and quotas (see Usage & Limits):

Feature example	Plan gating
Analyzer integration	Higher tiers
User seats	Per-plan cap
SMS volume	Monthly quota
Collection centers	Branch limit
Storage / backups	Retention days

Compare plans on /billing/plans before checkout.

Payment flow

1. Owner selects plan.
2. Checkout collects payment method (Payment Methods).
3. Gateway processes charge.
4. Webhook confirms subscription activation.
5. Lock cleared — full write access restored.

Development environments may use /billing/dev-pay for simulated payments.

Billing contact

Keep billing email current in Account Settings — renewal failures trigger read-only mode.

UI indicators

Component	Behavior
Trial banner	Countdown to trial end
Read-only banner	Lock reason + subscribe CTA
Subscription admin	Usage meters vs limits

Exempt API paths during lock

These remain writable or accessible for recovery:

• /auth, /billing, /tenant
• /public patient endpoints
• Payment webhooks

Laboratory mutations (POST/PUT/PATCH/DELETE on clinical routes) return 403 with TENANT_READONLY.

Platform vs tenant billing

Actor	Portal
Lab owner	Lab portal /billing/*
EaseLab operations	Admin portal tenant billing

Platform staff adjust plans, credits, and locks via Platform Administration.

Related documentation

• Plans & Checkout
• Usage & Limits
• Payment Methods
• Read-Only Mode
• FAQ: Billing