Appearance
Troubleshooting: Billing & Lockouts
EaseLab enters read-only mode when trials expire, subscriptions lapse, or platform admins manually lock a tenant. This guide explains symptoms, causes, and resolution.
Read-only mode symptoms
| Symptom | Detail |
|---|---|
| Lock banner in UI | Shows lock reason message |
| Can view data | Lists, reports, and search work |
| Cannot save | Create/edit/delete return HTTP 403 |
| Error code | TENANT_READONLY in API response |
| Billing works | /billing routes are exempt |
Automatic lock triggers
| Trigger | Lock reason (typical) |
|---|---|
| Trial expired | Your free trial has ended... |
| Subscription expired | Your subscription period has ended... |
| Manual lock | Custom reason from platform admin |
The TenantLockMiddleware enforces this on all mutation requests.
How to unlock
Self-service (tenant owner)
- Go to Billing → Subscription or Choose Plan.
- Select a plan and complete checkout.
- Submit manual payment proof (JazzCash, Easypaisa, bank transfer).
- Wait for platform admin approval.
- Lock clears automatically on approval.
See Billing: Plans & Checkout.
Platform admin unlock
- Verify payment received.
- Update tenant payment status to
Current. - Approve pending payment in admin portal.
- Or manually Unlock tenant:
POST /admin/tenants/{id}/unlock.
See Tenant Management.
Payment not approved
| Check | Action |
|---|---|
| Proof uploaded? | Re-submit on checkout page |
| Correct amount? | Match plan price exactly |
| Reference number? | Include transaction ID |
| Processing time | Allow 1–2 business days |
Contact platform billing with payment screenshot and tenant slug.
Trial extension
Only platform admins can extend trials:
- Open tenant in admin portal.
- Set new Trial ends at date.
- Set payment status to
Trial. - Unlock if currently locked.
Subscription usage limits
Separate from lock — plan limits may block specific features:
| Limit hit | Symptom |
|---|---|
| Max users | Cannot add staff |
| Max invoices | Warning or block on create |
| Analyzer feature | 403 on analyzer routes |
Check usage: GET /billing/usage
See Usage & Limits.
Payment account details wrong
If checkout shows incorrect JazzCash/bank details:
- Platform admin must update Payment Account.
- Do not send payments to unverified accounts.
API error reference
json
{
"code": "TENANT_READONLY",
"readonlyMode": true,
"message": "Your lab is in read-only mode. Subscribe to restore full access.",
"tenant": { "paymentStatus": "Unpaid", "isLocked": true }
}Client apps should detect readonlyMode and show billing CTA.
Prevention
| Practice | Benefit |
|---|---|
| Monitor trial end date | Renew before lock |
| Set calendar reminder | 7 days before expiry |
| Keep payment proof ready | Faster manual approval |
| Upgrade plan before limits | Uninterrupted operations |