Pricing Context

1. Introduction

A Pricing Context defines the environment in which the objects that produce a customer’s bill operate. Three real things interact inside it—a Pricing Module, a Subscription, and the Bill they exist to produce. The bill is what you actually wanted; the module and the subscription are instruments on the way to it.

The context itself holds no prices. It declares what exists; the objects built beneath it supply what things are worth. A Value declared here gets its number from a Pricing Module. A Component declared here gets its rules from a Pricing Module. A Subscription Property declared here gets its value from a customer’s Subscription. A meter reading hook declared here gets its readings from that same Subscription. An Invoice Template declared here gets its merge values when a Bill Run finally generates a Bill.

Everything defined here belongs to some other entity built underneath it, and only to entities built under this context, not any other:

Values and Components belong to the Pricing Modules built under this context. A Value is a lightweight slot that only stores a number or a simple calculation on numbers; a Component is more like a function, carrying Conditions and a Billing Formula that can reference Subscription Properties, Usage, and earlier Components.

Subscription Properties belong to the Subscriptions created when a customer subscribes to one of those Plans. The property is just a named slot here on the context—the customer’s actual value for it (their SLA Tier, their seat count) is captured on their own Subscription.

Usage also belongs to those same Subscriptions. Metered Usage and Unmetered Usage are just the tracking hooks defined here on the context—the actual readings and consumption amounts accrue against a specific Subscription each billing period.

The Invoice Template and Email Template belong to the Bills a Bill Run produces. They’re just the shared visual layout—the merge fields inside them ({partyName}, {KWH_currentReading}, {Electricity Charges}) only have real values once a Bill Run actually generates a Bill for a Billing Account in a given period. Every Bill rendered under this context uses this same template.

None of this crosses context boundaries. A Subscription created under a Plan built on a different Pricing Context doesn’t share this context’s Subscription Properties, Values, or Components—each context’s objects only ever belong to the Plans and Subscriptions built beneath it.

Two places a Pricing Module is used

A Pricing Module built on this context can be attached in two different places, and the context governs both:

• To a Subscription. A module marked Plan is subscribable—a customer subscribes to it and a Subscription is created. That Subscription is the billable unit, and its charges are this context’s Components, calculated by that module’s rules.
• To a Billing Account. A Billing Account is what actually receives an invoice. It carries a Pricing Module of its own, attached by an admin rather than subscribed to, which calculates the bill’s totals from the summed values of the Subscriptions inside it. See Single vs. Composite Billing Accounts.

So a Pricing Context governs both the rating of an individual Subscription and the assembly of the Bill that several Subscriptions roll up into.

The one thing that crosses contexts

The predefined Subtotal, Late Payment, Net Total, and Tax 1–5 components (see Required Components below) are the one exception. Because every Pricing Context is required to define them, they exist identically on every context—which is what lets a Composite Billing Account sum them across multiple Subscriptions, even Subscriptions built on entirely different Pricing Contexts. Any custom Component or Value stays scoped to its own context and can’t be aggregated this way; only these predefined components carry through to an account-level bill. See Single vs. Composite Billing Accounts for the full model.

2. Setup

Creating and configuring a Pricing Context is done directly in the admin console. Below is the step-by-step flow of how to navigate the context builder interface and configure each core structural pillar.

Step 1: Navigation

Navigate to: BillSpree → Billing Setup → Pricing Contexts. This displays the list of all existing Pricing Contexts. From here, you can create, edit, archive, or open a context to manage Pricing Modules and billing setups. Click on the New button in the upper right corner of the Pricing Contexts screen to launch the context creator.

Step 2: Setup Identity

Before opening any tab, configure the core identity of the Pricing Context itself:

• Identity Information: Define general metadata such as Name, Code, and Description to identify the context.

Pricing Contexts do not carry Security Attributes / ABAC scoping of their own. A Context is visible to anyone with admin access regardless of region, department, or tenant; security scoping only applies once you get to the Pricing Module level (Rate Cards, Charges Rules, Plans).

Step 3: Setup Values (The “Values” Tab)

Click on the Values tab. Here you define your Values—lightweight slots that only store a number or a simple calculation on numbers, with no conditions and no formula attached. Each entry has just an Order and a Name; the actual monetary value is assigned later, when building a Pricing Module. These names should align with the fields used in your attached Invoice Template.

• Examples: a fixed access fee like Platform Access Fee, a consumption rate like Per-GB Storage Rate, or a tier threshold like First 100 API Calls.

Step 4: Setup Components (The “Component” Tab)

Click on the Component tab. This is where you define your Components—function-like building blocks that can carry Conditions and a Billing Formula. A Component’s Conditions can reference Subscription Properties, Usage, and earlier Components (by Order); its Billing Formula can reference the same set. Only the component’s name and structural properties are set here on the context—the actual Conditions and Billing Formula are authored later, when building a Pricing Module. Multiple components can combine to produce a single bill line item; a component is a calculation unit, not necessarily a line item itself.

Each component has the following fields:

Field	Description
Order	Position in the calculation sequence. A component can reference any earlier component (by Order) in its formula, but never a later one—this guarantees no circular references.
Name	Identifies the component.
Account	The ledger account this component’s calculated amount posts to. Only present on components flagged Subtotal, Late Payment, or Tax—see below.
Payment Priority	Determines which component an incoming payment is applied against first. Lowest priority number settles first; if the payment doesn’t cover everything owed, it’s exhausted in priority order before later components see any of it. Only present on the same components that have an Account—Subtotal, Late Payment, and Tax—since only those have a posted balance to settle. Assigned automatically (see below).
Late Payment Flag	Marks the component as the one late payment surcharges apply against. Calculated at bill generation, but only posted once the grace period elapses unpaid.
Subtotal Flag	Marks the component representing the current cycle’s service charges only—tax is a separate, independently-posted component, not folded into Subtotal. This is what actually posts as billed revenue at bill generation.
Tax Flag	Marks the component as a tax line (up to 5 per context, see below).
Net Total Flag	Marks the component representing the bill’s running total (Subtotal + Tax + Arrears, later + Late Payment once applied). Has no Account—see below for why.
Calculation Type	Manual (a fixed number, no rule) or Calculated (governed by a Rule). This is a property of the component itself, decided once here on the context, not chosen separately by each Pricing Module built on it. It also controls visibility in the Module builder: a Calculated component appears as a tab you can author rules against; a Manual component doesn’t appear there at all.

Component Rules and Constraints

To ensure billing integrity, several rules apply when setting up components:

1. The Eight Predefined Components Every Pricing Context carries eight predefined components, whatever else is defined on it: Subtotal, Late Payment, Net Total, and Tax 1 through Tax 5. They are not optional and cannot be removed. Subtotal, Late Payment and Net Total are created with the context and always visible; all five Tax components exist from creation too, but only surface once you pick them (see Tax Components below).

They are compulsory for a reason. Because they exist identically on every context, they are the only vocabulary a Composite Billing Account can sum across Subscriptions built on different Pricing Contexts. Without a guaranteed shared set, a consolidated bill would not be possible at all. They are also the components every bill needs regardless of what it is billing for—somewhere for service charges to total, somewhere for tax, somewhere a late charge can land.

2. Dynamic Payment Priority Assignment The system automatically assigns dynamic, sequential payment priorities to billing components. When you mark a component as Subtotal, Tax, or Late Payment, the system scans currently used priorities in the context and automatically assigns the next available priority number. This ensures a single Pricing Context can have multiple independent tax components without priority level clashes during payment settlements.

Worked example

A customer’s bill has a Subtotal of $800 (Priority 1), a Late Payment charge of$150 (Priority 2), and a Tax component of $250 (Priority 3)—$1,200 owed in total. The customer pays $1,000.

The payment settles in priority order: $800 clears the Subtotal in full, leaving$200. That $200 clears the$150 Late Payment charge in full, leaving $50. That last$50 is applied against the $250 Tax component, leaving$200 of tax unpaid—which carries forward as arrears.

3. Tax Components All five Tax components exist on every Pricing Context. What varies is visibility—a Tax component only appears once you pick it, so a context for a tax-free jurisdiction or product simply never surfaces any. They can be surfaced at any time afterwards; nothing is lost by not using them at first.

You name the component yourself; the Account is what’s fixed. The ledger has five reserved accounts (system_Tax1 through system_Tax5), attached automatically and in sequence as you mark components with the Tax Flag. Once all five are in use, the tax checkbox on every other row is instantly disabled.

Because all five exist whether or not they were surfaced, summing tax across a Composite Billing Account is always safe. A context using no taxes contributes zero to the sum rather than being missing a component the other contexts have.

4. Which Components Have an Account Only three kinds of components have an Account at all: Subtotal, Late Payment, and Tax (up to 5). Every other component, including Net Total and any plain intermediate Calculated components feeding into Subtotal’s formula, has no Account field. There’s nothing to lock or grey out, it’s simply not part of those components’ structure.

Why only Subtotal, Late Payment, and Tax post

At bill run time, Subtotal (service charges only) and any Tax components are calculated and posted, each to its own account, these are the actual billed revenue and tax transactions for the cycle. Late Payment is calculated at the same time but posts later, only once the grace period elapses with the bill still unpaid.

Net Total is never one of the posting components. It’s a running display figure, Subtotal + Tax + Arrears (carried-forward unpaid amounts from prior cycles, already posted back when they were originally billed), and later + Late Payment once that’s applied. It aggregates amounts that are already posted independently by their own components, so it has nothing of its own to post.

The same applies to any plain intermediate component used only to help calculate Subtotal (via Component Chaining)—it’s a calculation step, not something that posts on its own.

None of this is automatic. Subtotal’s formula, Tax’s formula, Net Total’s formula, every Calculated component’s formula is explicitly authored by the user in the Pricing Module. The system can advise on how to write a rule, but it never writes or infers one for you.

These constraints make the Pricing Context more robust by preventing account mapping errors for system-calculated Totals, restricting tax distributions to the supported threshold, and enforcing conflict-free payment priorities.

Step 5: Setup Subscription Properties (The “Subscription Properties” Tab)

Click on the Subscription Properties tab. Here, you set up the dynamic data parameter fields (the “customer profile” hooks) required from the customer during checkout and used as inputs for your rating rules. Each property has a Name and a Type, and the type is one of:

• List: A set of predefined string values to choose from (e.g., SLA_Level: [“Gold”, “Silver”, “Bronze”], Deployment_Region: [“US-East”, “EU-West”]).
• Number: A numeric field (e.g., Committed_Seats, Included_API_Quota).

Special Subscription Properties

Two subscription properties are generated automatically, not defined by hand:

• Date — generated on every Pricing Context, regardless of what else is configured.
• A Yes/No property per Meter Property — generated automatically whenever a Meter Property is added (Step 6), flagging whether that cycle’s reading was estimated rather than actual.

Both are available as inputs anywhere a Subscription Property can be used—for example in Pricing Module rule conditions.

Step 6: Setup Meter Properties (The “Meter Properties” Tab)

Click on the Meter Properties tab. Define the tracking hooks to receive final readings from a physical or digital meter where continuous/odometer tracking is involved. The currently supported meter property types are:

• KWH
• Off-Peak Units
• Peak Units
• Cubic Meter Water
• Cubic Meter Gas

For each meter property, the billing engine expects to receive final/current readings at the end of the billing cycle. It then calculates net usage by subtracting the previous reading recorded on the previous bill (Net Consumption = Current Cycle Final Reading - Previous Cycle Final Reading).

• Example: An energy meter reads 15,000 kWh this month. Last month it read 14,200 kWh. The billing engine rates the net 800 kWh.

Each meter property also requires an estimation method, used when an actual reading is unavailable. See Usage Estimation for the five supported methods.

Step 7: Setup Unmetered Usage (The “Unmetered Usage” Tab)

Click on the Unmetered Usage tab. Set up hooks to receive direct, already calculated consumption amounts (delta usage) where no continuous meter is involved:

• Since the provided data is already the net consumption volume, the billing engine does not need to perform any subtraction or difference calculations.
• Examples: Receiving a direct record of 50 GB of bandwidth consumed or 10 hours of support time delivered during the billing period.

Step 8: Setup Bill Templates

• Default Invoice Template: Attach a master invoice template—typically a Word document (.docx)—which serves as the master visual layout for customer bills. This template contains merge placeholders (enclosed in curly braces {}) that the billing engine automatically populates when generating each bill. Placeholders come from two different sources—see Invoice Template Merge Fields below.
• Default Email Template: A text file (subject + content) sent alongside the bill, using the same merge-field placeholder style as the invoice template—but referencing bill-level fields rather than per-component charges.

Subject: Bill {billNo} - {serviceCode} - {billTermLabel}

Dear {partyName},

Your bill has been generated successfully.

Bill No: {billNo}
Pricing Context: {serviceCode}
Term: {billTermLabel}
Issue Date: {issueDate}
Due Date: {dueDate}
Amount: {total}

Please find your bill attached with this email.
If already paid, please ignore this message.

Regards,
Billing Team

Invoice Template Merge Fields

Placeholders fall into two categories, and only one of them is context-specific.

Fixed placeholders — always available on every Pricing Context, regardless of configuration:

Category	Placeholders
Party & address	{partyName}, {buildingName}, {buildingNo}, {street}, {city}
Subscription	{connDate}, {connectionNumber}, {tariffCode}
Bill metadata	{month}, {issueDate}, {dueDate}
Meter identity (per meter, up to 3)	{meter1No}, {meter1Type}, {meter1Status}—the same pattern repeats for meter2* and meter3*
Meter readings (per Meter Property type)	{KWH}, {KWH_previousReading}, {KWH_currentReading} for electric. The same three-field pattern applies to every Meter Property type from Step 6—for example {M3 Water}, {M3 Water_previousReading}, {M3 Water_currentReading} for water.

Component-derived placeholders — not fixed. Each one corresponds exactly to the Name given to a Value or Component in Step 3 or Step 4. A context with a component named Electricity Charges exposes {Electricity Charges}; one with a component named FC Surcharge exposes {FC Surcharge}. There’s no fixed list here—whatever Values and Components exist on a given context, under whatever names were chosen, become that context’s available placeholders.

A repeating bill-history table can be rendered with a loop block—{#billHistory}...{/billHistory}—with per-row fields like {billTerm}, a meter reading placeholder, and {amountPaid} inside it. An embedded chart/image placeholder ({%img1}) is also supported.

Example: an electricity bill template built with this merge-field system—fixed placeholders ({partyName}, {meter1Type}, {KWH_currentReading}), component-derived placeholders ({Electricity Charges}, {FC Surcharge}, {GST}), and a {#billHistory} loop block, all in one .docx:

---

3. Lifecycle Management

A Pricing Context has only two states:

State	Description
Created	The context exists and is immediately valid—the mandatory Subtotal, Late Payment, and Net Total flags are required at creation, so there’s no partial or draft state. Pricing Modules can be built on it right away.
Archived	The context is deactivated. All subscriptions tied to it must be deactivated first—archiving is blocked until every Pricing Module built on this context has no active subscriptions left. Once archived, no new Pricing Modules or subscriptions can be created from it.

View Variants is a separate, unrelated feature: a directory view displaying all the Pricing Modules built on this context. It’s a navigation aid, not a lifecycle state.

4. Editing an Existing Context

A Created context isn’t frozen. Each structural pillar has its own rules for what can change afterward.

Pricing Contexts don’t have versioning yet (tracked as a backlog item). Until it ships, every edit updates the live context directly and in place, there is no way to publish a change as a new version while leaving Pricing Modules on the old one intact. If a change is destructive (like reordering components), it breaks dependent Modules immediately. The system can warn you before you make the change, but it cannot protect you from it.

Name and Code: Locked once created. Only the Description can be edited afterward.

Default Invoice Template and Default Email Template:

• Both can be updated freely at any time.

Values and Components (the same underlying entity, so the same rules apply to both; up to 50 total, Values and Components combined, per context):

• Order can be changed.
• New Values or Components can be added.
• Existing ones can be deactivated (not deleted)—except whichever component carries the Subtotal, Late Payment, or Net Total flag. Those three can never be deactivated, since the context would no longer satisfy its mandatory requirement. Unlike reordering, deactivation does not break existing Pricing Modules.
• For Components specifically, Calculation Type (Manual/Calculated) and Payment Priority can also be updated directly.

Changing the Order of any Value or Component breaks every rule in every Pricing Module already built on this context. Order is what Component Chaining depends on, rules that reference “the component at this Order position” stop resolving correctly the moment that numbering shifts.

Subscription Properties (up to 30 per context):

• New Subscription Properties can be added.
• For List-type properties, new values can be added to an existing list.

Meter Properties:

• Locked once created. None can be added, and none can be edited.
• The only thing that can change is the estimation method assigned to an existing Meter Property.

Unmetered Usage (up to 30 per context):

• New Unmetered Usage entries can be added after creation, unlike Meter Properties.