Core Concepts

The Big Picture

StackBE is a multi-tenant billing platform.

That means:

• One StackBE instance
• Many tenants (organizations)
• Each tenant can run many apps
• Each app can have many customers
• Billing, subscriptions, and entitlements flow downward

Nothing leaks sideways.

Tenant

A Tenant represents an organization.

Examples:

• A solo founder
• A startup
• An internal platform team
• StackBE itself

A tenant owns:

• Apps
• Members (dashboard users)
• Payment gateway connections
• Billing configuration
• API keys (tenant-scoped)

Think: "Who owns this product?"

App

An App represents a product.

Examples:

• Your SaaS
• A side project
• A mobile app
• An internal tool
• StackBE Billing (yes, StackBE runs on StackBE)

An app owns:

• Customers
• Products
• Plans
• Subscriptions
• Webhooks
• App-scoped API keys

One tenant can run many apps.
Apps are isolated from each other by default.

Customer

A Customer is an end user of an app.

Customers:

• Belong to exactly one app
• Are identified by email (and optional external ID)
• Can have subscriptions
• Can authenticate via magic links
• Are not dashboard users

Customers are your users, not your team.

Product

A Product defines what you sell.

Examples:

• "Pro"
• "Team"
• "Enterprise"
• "API Access"

Products:

• Belong to an app
• Group one or more plans
• Are mostly organizational

Products are for humans. Plans are for billing.

Plan

A Plan defines how billing works.

Plans include:

• Price
• Currency
• Billing interval
• Trial length
• Entitlements
• Gateway mappings

Plans:

• Belong to a product
• Are what customers actually subscribe to
• Can be changed or deprecated safely

Customers subscribe to plans, not products.

Subscription

A Subscription links a customer to a plan.

A subscription tracks:

• Status (trialing, active, canceled, etc.)
• Current billing period
• Gateway reference IDs
• Cancellation intent
• Renewal state

Subscriptions are:

• Created automatically via checkout
• Updated by gateway webhooks
• Queried via API or customer portal

Entitlements

Entitlements define what a customer can do.

They are:

• Key-value or feature-based
• Attached to plans
• Evaluated dynamically

Example:

{
  "projects": 10,
  "apiCallsPerMonth": 100000,
  "features": ["analytics", "exports"]
}

Your app asks StackBE: "Does this user have access?"

StackBE answers with one API call.

API Keys

StackBE supports two scopes of API keys:

App keys should be used in production apps.
Tenant keys stay in admin tools.

Webhooks

Webhooks keep your app in sync.

Events include:

• Subscription created
• Subscription updated
• Payment succeeded
• Payment failed
• Checkout completed

Webhooks are:

• App-scoped
• Signed
• Retried automatically
• Logged for inspection

You can run fully async if you want.

Authentication Models

StackBE supports two distinct auth flows:

These never overlap.

"StackBE Runs on StackBE"

StackBE itself is:

• A tenant
• With an app called "StackBE Billing"
• Using subscriptions to manage access to StackBE

This proves:

• The model is sound
• No special cases exist
• You can do the same

If StackBE can bill itself, your app can bill anything.

What This Enables

This model allows you to:

• Run many apps under one account
• Charge per app, not per company
• Support free apps and paid apps together
• Grow without migrating billing systems later