Owner resale plans (Owner Plans)
This module lets a company owner define their own plan catalogue to resell to their own end customers — for example, an agency using Nimobase to manage client companies that wants to offer its own "Basic"/"Pro" tiers.
It is a concept separate from the platform's global plan catalogue (see Billing and subscriptions): that catalogue (/billing/plans) is what Nimobase sells to its tenants, and only a platform super admin manages it. This module (/companies/:id/owner-plans) is what each tenant sells to its own customers, and the owner/admin of that company manages it.
See the full design decision in the project's architecture documentation — this module implements only the partial scope described there (creating and editing your own catalogue); it does not implement the owner's end customers subscribing to those plans, nor any charging (see "Out of scope" below).
How it works
| Concept | What it is |
|---|---|
| Owner plan | A plan an owner defines for their own business, with a name, features (features) and limits (limits) — the same structure as the platform's global plans |
| Account subscription | The owner's own subscription to the platform (AccountSubscriptionEntity), which determines whether they can create resale plans |
Requirement to create plans: a subscription with resale enabled
Not every owner can create resale plans. The owner's account subscription (at user level, not for a specific company) must be active and the platform plan they are subscribed to must include the reseller_enabled feature — like any other feature controlled by features/limits in the platform plan catalogue.
If the owner has no active account subscription, or their plan does not include that feature, creating a new plan returns 403 Forbidden. This requirement applies only to creating a new plan — updating an existing plan (to deactivate it, for example) does not recheck the subscription.
Endpoints
All require Authorization: Bearer <token> and the OWNER or ADMIN role of the company named in the URL.
Listing your own catalogue
GET /companies/:id/owner-plans
Authorization: Bearer <token>Returns only the plans created by that company.
Automatic Base/Pro/Max starter pack: if the owner's account subscription has reseller_enabled and their resale catalogue is still empty, this same call automatically instantiates 3 starter plans — Base, Pro and Max — with the same system characteristics an end customer sees (max_users, max_companies, api_access, priority_support, custom_domain), without reseller_enabled on any of the three (resale is single-level: platform → reseller → end customer, never reseller → reseller). There is no need to create these plans by hand or to go through any special flow: it is enough for the owner to open the "Resale plans" screen (or for any caller to query this endpoint) with an empty catalogue. If the catalogue already has any plan (even one not called Base/Pro/Max), this automatic instantiation does not run — it neither adds nor overwrites existing plans. The 3 instantiated plans are normal rows, fully editable afterwards (rename, adjust features/limits, deactivate) just like any plan created by hand.
Creating a resale plan
POST /companies/:id/owner-plans
Authorization: Bearer <token>
Content-Type: application/json
{
"name": "Client Basic Plan",
"description": "Entry tier for my customers",
"features": ["priority_support"],
"limits": { "max_users": 5 }
}Answers 403 when the creator's account subscription does not enable resale (see above).
Catalogue validation: features and limits may only use keys from the system catalogue plus this company's own non-archived custom ones (see the next section). An unknown key, a key of the wrong type (flag vs limit), reseller_enabled or any other platform-only option, or a negative or non-numeric limit, are rejected with 400. Limits accept a number ≥ 0 or null (unlimited). This rule prevents bypassing the reseller's pool by inventing keys or negative limits.
Updating a plan
PATCH /companies/:id/owner-plans/:planId
Authorization: Bearer <token>
Content-Type: application/json
{ "isActive": false }If the body includes features and/or limits, the same catalogue validation as on creation applies. A custom option already granted on the plan may stay even if it is archived later; an archived key cannot be added anew.
The company's own custom catalogue
Like the platform (see Billing and subscriptions), each reseller company can add its own custom features/limits, reusable across its resale plans, on top of the system options (max_users, max_companies, api_access, priority_support, custom_domain).
GET /companies/:id/catalog/custom-options[?includeArchived=true]
POST /companies/:id/catalog/custom-options
POST /companies/:id/catalog/custom-options/:optionId/archive
POST /companies/:id/catalog/custom-options/:optionId/unarchiveRequires the OWNER or ADMIN role of company :id. Archiving a custom option (as on the platform) is a soft mark — it never deletes the row, so plans already using it keep their value; it merely stops being offered when adding options to a new plan.
Assigning a plan to a client company
A reseller can link one of its client companies to one of its own resale plans — just the link, with no charging and no billing period (that is left for a later delivery).
POST /companies/:id/owner-plans/:planId/assign
Authorization: Bearer <token>
Content-Type: application/json
{ "clientCompanyId": "..." }Requires the OWNER or ADMIN role of the reseller company (:id).
Scope: on the first assignment, the target company must already be a client of the reseller: its creator (ownerId) must be a member of the reseller company. If not (someone else's company, an orphan/system company, or one only known by UUID), the call is rejected with 403 and the message This company is not a client of this reseller. A UUID with no prior link is not enough to claim the company.
If the client company already had another plan from this same reseller assigned, this call changes it (the same endpoint both assigns and changes) and does not recheck the creator's membership — the link already exists. If the client company is already linked to a different reseller, the call is rejected with 403 — each client company can belong to only one reseller's "scope" at a time.
GET /companies/:id/owner-plan-assignmentsLists, for reseller :id, all its client companies with an assigned plan (OWNER/ADMIN role).
GET /companies/:id/owner-plan-assignmentFrom the client company's side (:id): returns its assigned plan, or null when there is none (with no plan assigned, no resale limit or feature applies to that company). Any authenticated member of the company can query it.
The reseller's shared pool
A reseller cannot hand out more capacity than its own platform plan gives it. Every time a plan is assigned or changed for a client company, the system sums the system limits (max_users, max_companies) committed across all the plans already assigned to its client companies — including the new or changed one — and compares the total against the reseller's own platform plan limits. If the sum would exceed the quota, the assignment is rejected with 409 and reports the remaining quota.
Example (from the spec): a reseller on the Max platform plan (150 users) cannot have four client companies on a Max resale plan of 45 users each (180 > 150) — the fourth assignment is rejected.
If the reseller has no platform plan with those limits yet (for example, in an environment without billing configured), this check simply does not apply — it does not block flows that do not depend on billing.
Real-time enforcement on the client company
Once assigned, the resale plan governs that specific client company's operations in real time — it is not merely checked at assignment time. OwnerPlansService exposes two methods that CompaniesService/ApiKeysService consume (backend-api/src/api/companies/, backend-api/src/api/api-keys/):
getEffectiveEntitlement(clientCompanyId, feature)— resolves whetherfeatureis granted for that client company right now:{ assigned: false }when no resale plan is assigned (it falls back to the usual platform plan);{ assigned: true, has: false }when a plan is assigned but does not declarefeature(omitting it is a deliberate "not granted", as on the platform);{ assigned: true, has: true, limit }when it grants it (limitnumeric for limit keys,nullfor boolean flags such asapi_access).assertResellerPoolNotExceeded(clientCompanyId, feature)— besides the assigned plan's own limit, an addition must also respect the reseller's current pool (which may have shrunk after the assignment if the reseller changed or cancelled their own platform plan).
CompaniesService.assertUnderPlanUserLimit() (member additions) and ApiKeysService.assertApiAccessEnabled() (API key creation) consult getEffectiveEntitlement() first; only when no resale plan is assigned do they fall back to the pre-existing platform plan check.
Out of scope for this module
By design, this module does not implement:
- The owner's end customers subscribing with charging to these plans — the plan↔company link (above) exists, but without a billing period or payment.
- Any charging integration for the owner → end customer flow (Stripe Connect or otherwise).
Real-time enforcement of the assigned plan's limits/features on the client company's operations is implemented — see the section above.
That charging piece remains future work.