Skip to main content

Organizations

The Organizations page at kuploy.app/organizations shows all your end-customer organizations across every kuploy-cloud instance — giving you a unified view of who is using your platform and how much they're consuming.

Who Are "Organizations"?

Organizations are the teams or companies that use your kuploy-cloud instances. Each instance can host multiple organizations. This page aggregates them all in one place so you can monitor usage and manage plan assignments.

Accessing Organizations​

  1. Sign in to kuploy.app
  2. Click Organizations in the top navigation bar

Summary Cards​

At the top of the page, three cards provide a high-level snapshot:

CardDescription
OrganizationsTotal number of unique organizations across all instances
Across InstancesNumber of unique kuploy-cloud instances reporting organizations
Total Team MembersSum of team members across all organizations

Organization Cards​

Each organization is displayed as a card showing:

  • Organization name (or ID if no name is set)
  • Instance location — which instance the org is on, or "Across N instances" if the org spans multiple
  • Plan badge — the assigned plan template name (shown in blue), or "No plan" if unassigned

Usage Metrics​

Each card shows the org's current resource consumption:

MetricIconDescription
ProjectsFolderNumber of projects
AppsWindowNumber of deployed apps
DatabasesDatabaseNumber of provisioned databases
DomainsGlobeNumber of configured domains
MembersUsersNumber of team members
Build MinutesClockBuild minutes consumed this period
StorageDriveStorage used (displayed as MB or GB)

Usage Bars​

When an organization has a plan assignment, usage bars appear below the metrics showing consumption against limits:

  • Green bar — below 80% of limit
  • Yellow bar — between 80–99% of limit
  • Red bar — at or above 100% (limit reached)

Usage bars only appear when an org has a plan assigned. Orgs without plan assignments show raw usage numbers only.

Multi-Instance Indicator​

If the same organization exists on multiple kuploy-cloud instances (identified by matching org ID), the card shows:

  • "Across N instances" in the description
  • A list of all instances at the bottom of the card
  • Aggregated usage — usage from all instances is summed together

How Organization Data Gets Here​

Organizations appear automatically — no manual entry required. The data flows through the license sync process:

kuploy-cloud instance          kuploy.app
┌─────────────────────┐        ┌─────────────────────────┐
│  License sync runs  │  POST  │  /api/license/sync      │
│  every 5 minutes    │───────►│                         │
│                     │        │  Upserts each org into  │
│  Reports:           │        │  the instance_org table  │
│  • Per-org usage    │        │  with latest usage data  │
│  • Org ID + name    │        │                         │
└─────────────────────┘        └─────────────────────────┘
  1. Each kuploy-cloud instance syncs its license every 5 minutes
  2. During sync, it reports all organizations and their per-org usage
  3. kuploy.app stores this in the instance_org table
  4. The Organizations page queries this data scoped to your tenant
New Instance?

After connecting a new kuploy-cloud instance via license, its organizations will appear within 5 minutes (the next sync cycle).

Per-Organization Plans​

Each organization can be assigned its own plan tier, allowing you to offer different service levels to different customers.

How Plan Assignment Works​

ConceptDescription
Plan templateA plan from your catalog (defined in kuploy.app under Customers > Plans)
Custom limitsOptional overrides for specific limits (e.g., more projects than the plan template allows)
Custom featuresOptional feature flag overrides (e.g., enabling custom domains on a lower tier)

When an org has a plan assigned:

  1. The plan template's limits are loaded
  2. Any custom limit overrides are merged on top
  3. The resolved limits are synced to the kuploy-cloud instance and enforced
  4. Usage bars on the Organizations page show consumption against these resolved limits

Assigning Plans​

Plan assignments are managed through the Customers > Plans page in kuploy.app. Each org is assigned a plan template by its templateId — this is the sole source of truth for that org's resource limits.

For details on setting up plans for your customers, see Cloud Billing Setup.

Deactivating Plans​

You cannot deactivate a plan template while organizations are still assigned to it. If you attempt to deactivate a plan that has assigned orgs, you'll see:

Cannot deactivate "Pro" — 3 org(s) are still assigned to it. Reassign them first.

To deactivate a plan, first reassign all its organizations to a different plan template.

Default Plan​

You can designate one plan as the default for new organizations. When a new org is created on a kuploy-cloud instance and syncs for the first time, it inherits the default plan automatically.

Organizations Without Plans​

Organizations that don't have a plan assignment:

  • Still appear on the Organizations page with full usage metrics
  • Are not individually limited — they operate under the aggregate license limits
  • Show no usage bars (since there are no per-org limits to compare against)

This is common during initial setup or if you don't need per-org billing.

Empty State​

If no organizations appear, it means:

  • Your kuploy-cloud instances haven't synced yet (wait up to 5 minutes)
  • No organizations have been created on your instances yet
  • Your license may not be connected — check Licensing

Frequently Asked Questions​

Can the same organization exist on multiple instances?​

Yes. If the same org ID appears on multiple kuploy-cloud instances, the Organizations page aggregates their usage and shows all instances. This is useful for multi-region or load-balanced deployments.

How often does usage data update?​

Usage updates every 5 minutes during license sync. The data you see reflects the most recent sync from each instance.

Can I set different limits for the same plan per org?​

Yes. Each org's plan assignment supports custom limit overrides. For example, you could assign two orgs to the Growth plan but give one org extra build minutes.

What happens when an org hits its limit?​

Resource creation for that specific resource type is blocked on the kuploy-cloud instance. The org's users see an error message directing them to upgrade. For details, see Plans & Usage.