Billing and plans
Billing answers one question for the rest of the code: may this tenant do this? Packages (plans) carry features and limits, a tenant subscribes to a package, and resource services ask the billing guard before they create anything.
package ──has──► package_features (feature_key, is_enabled, limit_value) ▲ │ package_idsubscription (tenant_id, status, expires_at, overrides) ──► payments ──► approval requestsEverything is stored in Postgres (packages, package_features, subscriptions, payments,
payment_approval_requests). Billing management — editing plans, approving payments — belongs
in your product’s admin app, which calls the endpoints below; the developer dashboard only shows
each tenant’s plan and usage for debugging.
Features and limits
The catalog of features is in Go — internal/modules/billing/domain/features.go:
| Kind | Features |
|---|---|
| Limits (numbers) | users.max, branches.max, storage.mb |
| Switches (booleans) | patients.manage, appointments.manage, invoices.manage, reports.basic, reports.advanced, reports.export, sms.notifications, api.access, audit.log, custom.branding |
A limit of -1 means unlimited. Resolution: the subscription’s overrides → the package’s
features → denied.
Enforcing a limit
Resource services depend on a one-method interface, not on billing:
type LimitChecker interface { // QuotaFor reads the plan limit (before any lock) and returns a check // that only compares numbers. QuotaFor(ctx context.Context, tenantID int64, feature string) (func(current int64) error, error)}users.max and branches.max are enforced by identity and branches under a per-tenant advisory
lock (see Database → Quotas); storage.mb by the files
service on uploads. A refusal is a 402:
{ "error_code": "USAGE_LIMIT_EXCEEDED", "status": 402, "meta": { "feature_key": "users.max", "limit": 5, "current": 5 } }…or SUBSCRIPTION_REQUIRED when the tenant has no active plan. For a boolean feature, call
guard.Require(ctx, tenantID, domain.FeatureReportsExport).
Subscriptions
Statuses: trial, pending, active, past_due, cancelled, expired. Only active and
trial grant access.
| Action | How |
|---|---|
| tenant subscribes | POST /api/v1/billing/subscribe {package_id, payment_method, payment_data} |
| see the current plan | GET /api/v1/billing/subscription/status |
| staff assigns a plan | POST /api/v1/billing/internal/tenants/{tenant_id}/subscription |
| staff cancels | POST /api/v1/billing/internal/subscriptions/{id}/cancel — immediate |
| expiry | the billing.expire-subscriptions task, every 6 hours |
| renewal reminders | billing.send-renewal-reminders, daily at 08:00, at 7/3/1 days |
Subscribe is idempotent per tenant + package + method: while a checkout is pending, a retry or double click returns the same checkout instead of charging twice (a per-tenant lock serialises it). Activating a subscription deactivates the previous one in the same transaction.
Staff assignment
Support, sales deals and complimentary accounts use the assign endpoint (subscription.manage):
POST /api/v1/billing/internal/tenants/7/subscription{ "package_id": 2, "payment_method": "cash", "amount": 150000 }It ends the current subscription and starts an active one in one transaction. With
payment_method (cash or bank_transfer) it records a completed payment — amount defaults
to the package price; without it the plan is free of charge. Hidden (inactive) packages can be
assigned.
Overrides
Per-tenant exceptions live on the subscription (subscription.override):
POST /api/v1/billing/internal/subscriptions/12/overrides{ "overrides": { "users.max": 25, "reports.export": true, "branches.max": null } }Values merge in; null removes an override so the feature falls back to the plan. A new
subscription starts with none.
Payments
An orchestrator picks a driver per method:
| Method | Flow |
|---|---|
bkash |
tokenized checkout; the token is cached 55 minutes and dropped on 401/403 |
cash, bank_transfer |
a pending payment + a staff approval request |
nagad |
stub, ready for a real driver |
- Callbacks (
GET /api/v1/billing/{gateway}/callback) are public and only a hint: bKash is always asked for the real status. Only a status bKash reports as failed or cancelled fails a payment; a gateway error is a retryable 503 that changes nothing. Completion and activation are one transaction. - Approvals:
POST …/payment-approvals/{id}/approve|rejectupdate the payment and the subscription atomically. - Invoices are
INV-XXXX-timestampfromcrypto/rand; cash and bank payments get unguessableCASH-…/BANK-…references. - Payment statuses only move along allowed transitions (pending → any, failed → completed, completed → refunded).
Packages
GET /api/v1/public/packages lists active packages for your pricing page (no auth). Staff manage
packages with /api/v1/packages (package.*); updating a package replaces its feature set
in one transaction. Money is in minor units of BILLING_CURRENCY (default BDT).

