Skip to main content

Account Hierarchy

Opencell uses a hierarchical account structure to manage customers, billing, and subscriptions.

Account Structure​

Provider (Tenant)
└── Seller
    └── Customer
        └── CustomerAccount (payment level)
            └── BillingAccount (invoice level) ← BillingCycle assigned here
                └── UserAccount (consumption level)
                    └── Subscription → Services → Charges

Provider​

The top-level tenant entity representing the billing platform instance.

Key Fields:

  • code - Unique identifier
  • currency - Default currency
  • country - Default country
  • language - Default language
  • roundingMode - How amounts are rounded

Note: Provider.CURRENT_PROVIDER_ID = 1L is hardcoded per schema for multi-tenancy.

Seller​

Sales entity representing a business unit or reseller.

Key Fields:

  • code - Unique identifier
  • tradingCountry - Country for tax purposes
  • tradingCurrency - Currency for transactions
  • tradingLanguage - Language for documents

Customer​

The end customer being billed.

Key Fields:

  • code - Unique identifier
  • customerCategory - Classification (PROSPECT, CUSTOMER, etc.)
  • customerBrand - Brand association
  • seller - Parent seller

CustomerAccount​

Payment-level account for receivables management.

Key Fields:

  • customer - Parent customer
  • currency - Account currency
  • status - ACTIVE → CLOSE
  • paymentMethods - Payment methods (credit card, direct debit, etc.)

BillingAccount​

Invoice-level account where billing cycles are configured.

Key Fields:

  • customerAccount - Parent customer account
  • billingCycle - CRITICAL: Determines when invoicing happens
  • invoicingThreshold - Minimum amount to invoice
  • country - Tax country
  • language - Invoice language
  • electronicBilling - Enable eInvoicing

UserAccount​

Consumption-level account for tracking usage.

Key Fields:

  • billingAccount - Parent billing account
  • status - ACTIVE → CANCELED → TERMINATED → CLOSED
  • subscriptions - Child subscriptions

Status Lifecycles​

CustomerAccount Status​

ACTIVE → CLOSE

BillingAccount/UserAccount Status​

ACTIVE → CANCELED → TERMINATED → CLOSED

Invoicing Thresholds​

The IInvoicingMinimumApplicable interface defines threshold behavior at multiple levels:

LevelField
CustomerinvoicingThreshold
CustomerAccountinvoicingThreshold
BillingAccountinvoicingThreshold
BillingCycleinvoicingThreshold

Threshold Options (ThresholdOptionsEnum):

  • BEFORE_DISCOUNT - Check threshold before discounts
  • AFTER_DISCOUNT - Check threshold after discounts
  • POSITIVE_RT - Only positive rated transactions
  • POSITIVE_IL - Only positive invoice lines

Multi-Tenancy​

Provider-Based Isolation​

Each Provider gets a separate database schema:

  • opencell_provider_1
  • opencell_provider_2

Seller-Based Logical Isolation​

Within a Provider, Sellers provide logical separation:

  • Same schema, different business units
  • Not GDPR-compliant (shared database)

See Multi-Tenancy Architecture for detailed deployment patterns.

Creating Account Hierarchy​

Option 1: Step-by-Step API Calls​

# 1. Create Customer
POST /api/rest/v2/account/customer

# 2. Create CustomerAccount
POST /api/rest/v2/account/customerAccount

# 3. Create BillingAccount
POST /api/rest/v2/account/billingAccount

# 4. Create UserAccount
POST /api/rest/v2/account/userAccount
POST /api/rest/v2/account/accountHierarchy/customerHierarchyUpdate

See Customer Hierarchy API for details.