Skip to content

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_id
subscription (tenant_id, status, expires_at, overrides) ──► payments ──► approval requests

Everything 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|reject update the payment and the subscription atomically.
  • Invoices are INV-XXXX-timestamp from crypto/rand; cash and bank payments get unguessable CASH-… / 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).