Concepts and system flow

This page is an Explanation. It gives you a global mental model of Vluna: the main objects, and how data flows through the system.

Vluna is built to support two common monetization paths (usage-based and outcome-based), but the system model is one end-to-end flow. Both paths converge into the same accounting primitives: rating, settlement, ledger, and balance.

The system at a glance

Vluna links these building blocks:

• Identity: principal_id and billing_account_id.
• Account profile: billing details attached to billing accounts.
• Billable resources model: feature_families, features, and meters.
• Packaging and enforcement: entitlements and gate policies.
• Commercial terms: billing plans, plan assignments, and contract terms.
• Money: XUSD, funding, and the ledger.
• Runtime: authorization, metering, and rating.
• Attribution (Enterprise): mapping rated usage to plan/subscription ownership.

End-to-end flow

Start with this diagram. It shows how the main objects connect. Use the Key objects table below as a lookup.

Vluna has multiple entry points (checkout, direct assignments, runtime commits, outcome events), but the system flow is consistent.

Your catalog product / price
  |
  | (1) Identify who pays
  v
principal_id  ---->  billing_account_id (stable 1:1 mapping)
  |
  | (2) Define what is being used, consumed and enforced
  v
Feature Families / Features / Meters
  |
  | (2b) Package and enforce access
  v
Entitlements + gate policies (limits)
  |
  | (3) Define commercial terms
  v
Billing plans  +  Contracts and contract terms (optional)
  |
  | (4) Apply terms to a customer account (two common paths)
  |     A. Catalog and checkout (optional, provider-backed)
  |     B. Direct plan assignment (API-driven)
  v
Plan assignments -> active terms for the billing account
  |
  | (5) Fund the account (optional but common)
  |     - Plan-issued credits (if your plan includes recurring credits)
  |     - Checkout purchases (for example, one-time credit topups)
  |     - Grant programs -> grant assignments
  v
Available balance and limits (in XUSD)
  |
  | (6) Run work and record usage or outcomes
  |     - Usage path: authorize -> work -> commit (lease token + meters)
  |     - Outcome path: ingest events -> event rating policy -> ratings
  v
Ratings (authoritative billable records)
  |
  | (7) Settle and audit
  v
Settlement -> ledger entries -> balances + reports
  |
  | (8) Invoice and collect (optional)
  v
Invoices and payments (or export to your billing provider)

Key objects (what they are and why they exist)

Use this as a map when you read Tutorials, Guides, and API Reference.

Object	What it represents	What developers do with it
Realm	Your project boundary	Set it once per app and send X-Realm-Id on every request
Service key	Server-to-server credentials	Store securely on the server and use it for /mgt/v1
principal_id	Your stable identifier for who pays	Choose a stable id (customer, org, team, tenant)
billing_account_id	Vluna's account identifier	Store it and treat it as account-scoped and sensitive
Billing details	Account billing profile (billing_account_billing_details)	Store legal/entity/contact/tax profile separately from authorization and entitlement logic
Feature Family	A group of features	Use it to organize entitlements and product packaging
Feature	An enforceable unit of access	Define what a customer can do and gate it at runtime
Meter	A measurable unit of usage	Record usage quantities to price and settle consumption
Billing plan	A named set of commercial terms	Define what you sell and how it is priced and limited
Plan assignment	Which plan applies to an account	Assign a plan to a billing_account_id (directly or via checkout)
Entitlement	What a plan includes and allows	Define what features are available under a plan
Gate policy bundle	A named set of gate policies	Assign a default bundle or switch bundles per account when needed
Gate policy	Runtime limits and enforcement rules	Define rate, quota, or seat limits per feature
Lease token	A short-lived authorization for a unit of work	Bind a unit of work to limits and safe retries
Contract	Account-specific commercial agreement	Attach negotiated terms to an account when needed
Contract terms	Versioned contract parameters and overrides	Apply negotiated pricing and terms for specific customers
Catalog product (optional)	A purchasable product definition	Define what can be sold through a self-serve purchase flow
Catalog price (optional)	A purchasable price option	Define how a catalog product is priced (including credit topups)
Subscription (optional)	A provider-backed purchase state	Use it only if you expose a subscription flow to end users
Billing period (optional)	A billing cycle boundary	Use it if you generate invoices or statements by period
Invoices and payments	Customer-facing billing artifacts	Keep your existing billing stack, or skip and manage funding yourself
Grant program	A template for credits and funding rules	Define promotions, trials, or funded budgets
Grant campaign	A named operational rollout	Group grants for reporting and safe rollback
Grant assignment	A grant instance for an account	Grant credits to a billing account with an expiry and constraints
Budget (optional)	A spend boundary for an account	Define spend caps and budgeting behavior when needed
Event	A facts-only business record	Ingest outcome events for outcome-based billing
Event rating policy	Rules that turn events into billable ratings	Define how business events become billable results
Rating	The billable decision for a unit of work	Treat it as the source of truth for settlement and audit
Rating attribution (Enterprise)	Ownership mapping for a rating (plan, plan_assignment, subscription, subscription_item)	Use it for cost ownership analysis, reporting dimensions, and traceability
Settlement	Posting rating results into accounting	Allocates amounts and posts ledger entries
Ledger entry	The immutable accounting record	Use it for reconciliation, reporting, and disputes

If you need a canonical definition of a term, use the Glossary:

• Glossary

What you should touch vs what you should observe

As an integrator, you usually:

• Define your billable resources model: feature_families, features, meters.
• Define what you sell: billing plans.
• Decide how plans are applied: checkout flow, direct plan assignment, or both.
• Decide how accounts are funded: plan-issued credits, grants, and purchases.
• Call runtime APIs to authorize work and commit usage, or ingest outcome events.

You should always observe and log:

• Success vs denial and the denial reason (for safe degradation).
• Idempotency behavior and conflict errors (for safe retries).
• Rating and ledger ids (for reconciliation and support).

Where to go next

• Verify your integration baseline: Verify installation and integration
• Run a first success tutorial: Your first 10 minutes
• Browse task guides: Guides