Pricing User Guide

The Pricing module is where you define reusable pricing packages, attach them to business targets, and inspect how the engine resolves and executes them.

Navigation: Administration -> Financial Setup -> Pricing

This page is the operational home for:

• pricing profiles
• pricing items
• profile composition
• item dependencies
• bindings
• overrides
• pricing line codes
• rate indices
• pricing context preview

Core Concepts

Pricing Profile

A pricing profile is a reusable pricing package.

Examples:

• retail loan pricing
• staff loan pricing
• savings maintenance pricing
• fixed deposit maturity pricing

Profiles can contain items directly and can also include other profiles through Profile Links.

Pricing Item

A pricing item is one monetary rule inside a profile.

Examples:

• processing fee
• origination fee
• daily interest
• tax on fee
• penalty on overdue charge

Each pricing item defines:

• the line code
• the calculation handler
• the rate or fixed amount setup
• the posting rule
• optional trigger transaction type

Profile Links

Profile links are how you compose one profile from other profiles.

Use this when a business profile should include reusable pricing libraries, for example:

• a loan profile includes a fee profile
• a deposit profile includes an interest profile

Item Dependencies

Item dependencies are how one pricing item depends on another pricing item.

Examples:

• tax on processing fee
• penalty on overdue interest
• discount on another charge

This is not the same as profile composition.

Bindings

Bindings attach pricing to a real business target.

Examples:

• product-level pricing
• account-level pricing
• item-level pricing binding

Overrides

Overrides let a profile specialize an inherited pricing item without duplicating the whole item definition.

Examples:

• change the rate only
• disable one inherited item
• change a fixed amount for one profile

Pricing Screen Layout

The Pricing screen has three tabs:

• Pricing
• Line Codes
• Rate Indices

Pricing Tab

The Pricing tab is the main working area.

From each pricing profile row you can open:

• View Items
• Preview Context
• Profile Links
• Bindings
• Overrides
• Edit

How To Create And Maintain A Profile

1. Open the Pricing tab.
2. Click Add Profile.
3. Fill in the basic profile information.
4. Save the profile.
5. Open View Items to add pricing items.
6. Open Profile Links if this profile should include other profiles.
7. Open Bindings if this profile should be attached to products or records.
8. Open Overrides if this profile needs to specialize inherited items.
9. Open Preview Context to validate the effective pricing graph.

Profile Form Fields

The profile form defines the reusable package shell. These are the main fields users maintain directly.

Field	What it means	Engine implication
Profile Name	Business-facing name for the pricing package.	Used in admin UI, preview, diagnostics, and resolver traces.
Description	Plain-language purpose of the profile.	Does not change pricing math, but is important for support and audit readability.
Active	Whether the profile is available for effective resolution.	Inactive profiles stay in configuration history but should not resolve as active pricing roots or included profiles.
Default Posting Rule	Optional fallback GL mapping for items in the profile.	Used only when a pricing item does not carry its own item-level posting rule.

Important:

• profile_code is backend-generated. Users do not type it.
• profile items are maintained separately, either inside the profile form or through View Items.

Profile Items

Open a profile row and click View Items.

This opens the profile items dialog where you can:

• add items
• edit items
• delete items
• open dependencies for a specific item

Profile Item Form Breakdown

The item form is divided into logical sections.

Item Identification

Main fields:

• Line Code
• Line Name
• Calculation Handler
• Application Mode
• Trigger Transaction Type

Use this section to define what the pricing item is and which handler computes it.

Field guidance:

• Line Code: selects the master pricing line. This drives the component category, allowed calculation styles, and validation rules used by the resolver.
• Line Name: business-facing label shown in profile item lists, pricing preview, diagnostics, and execution traces.
• Calculation Handler: runtime calculator that actually computes or applies the item. Dependent items normally need a parent-aware handler.
• Application Mode: controls whether the item is expected to run manually on an event, on a scheduled cycle, or in arbitrary/manual runtime flows.
• Trigger Transaction Type: optional system transaction code used by transaction-triggered pricing hooks. Leave blank when the item is not tied to a specific transaction family.

Supported trigger transaction types include:

• CASH_DEPOSIT
• CASH_WITHDRAWAL
• DEPOSIT
• WITHDRAWAL
• FEE
• INTEREST
• LOAN_DISBURSEMENT
• LOAN_REPAYMENT

Full Profile Item Field Reference

Identification And Runtime Selection

Field	What it means	Engine implication
Line Code	Master pricing line selected from line-code setup.	Defines the component category and whether fixed/rate-based pricing is allowed. This is one of the main semantic controls in resolver validation.
Line Name	Business-facing label for the item.	Appears in previews, runtime traces, pricing transactions, and user diagnostics.
Calculation Handler	Runtime calculator or action handler.	Determines how the item is computed or applied. Dependent items usually need a parent-aware handler.
Item Posting Rule	Optional GL mapping attached to the item itself.	Overrides the profile default posting rule for this item only.
Application Mode	One of MANUAL, SCHEDULED, or ARBITRARY.	Controls whether the item is expected on explicit business events, recurring cycles, or freer runtime orchestration.
Trigger Transaction Type	Optional system pricing transaction code such as CASH_DEPOSIT, CASH_WITHDRAWAL, LOAN_DISBURSEMENT, or LOAN_REPAYMENT.	Filters the item so transaction-triggered hooks only execute items whose system code matches the originating transaction family. Leave blank for non-transaction-driven items.

Rate And Amount Setup

Field	What it means	Engine implication
Rate Source Type	One of FIXED, INDEXED, TIERED, or NONE.	Determines which pricing inputs are valid and which runtime path the handler should follow.
Rate Value (%)	Percentage value for fixed percentage pricing.	Used when the item is rate-based and the selected line/handler permit rates.
Fixed Amount	Flat amount for the item.	Used when the item is amount-based rather than percentage-based.
Index Rate Code	Managed rate index selected from the rate-index list.	Used only for indexed pricing. The engine reads the latest approved index history and can emit repricing logs when the index changes.
Spread / Margin (%)	Extra percentage added on top of the chosen index.	Used only for indexed pricing to compute effective runtime rate.
Balance Basis	One of AVERAGE_DAILY_BALANCE, MINIMUM_DAILY_BALANCE, or END_OF_DAY_BALANCE.	Tells balance-driven handlers which balance snapshot to read.
Day Count Convention	One of ACTUAL_365F, ACTUAL_360, THIRTY_E_360_ISDA, or ACTUAL_ACTUAL_ISDA.	Controls how annualized or time-based pricing is prorated. Most relevant for interest-style pricing.

Limits, Review, And Repricing Inputs

Field	What it means	Engine implication
Min Amount	Optional floor on the computed result.	Prevents a rate-based result from falling below the configured amount.
Max Amount	Optional cap on the computed result.	Prevents a rate-based result from exceeding the configured amount.
Max Balance For Calc	Optional ceiling on the balance amount the handler can read.	Limits the balance exposure used by the handler without changing the underlying account balance.
Review Frequency Unit	One of DAY, MONTH, or YEAR.	Used for periodic review or repricing style behavior.
Review Frequency Interval	Number of review units between reviews.	Completes the review cycle definition and supports periodic repricing/reassessment logic.

Lifecycle And Eligibility

Field	What it means	Engine implication
Active	Whether the item is currently enabled.	Inactive items remain in history but are excluded from effective resolution and execution.
Effective From	Optional start date.	The resolver ignores the item before this date.
Effective To	Optional end date.	The resolver ignores the item after this date.

Tier Rows

Tier rows are only used when Rate Source Type = TIERED.

Field	What it means	Engine implication
Tier Min Value	Start of the amount or band range.	Helps the handler choose the correct tier.
Tier Max Value	End of the amount or band range.	Helps the handler choose the correct tier.
Tier Rate Value (%)	Percentage used by that tier.	Used when the selected tier is rate-based.
Tier Fixed Amount	Flat amount used by that tier.	Used when the selected tier is amount-based.
Priority	Numeric precedence among tiers.	Used for deterministic tier evaluation order.
Period From (Month)	Optional duration-band start month.	Supports time-banded tier logic.
Period To (Month)	Optional duration-band end month.	Supports time-banded tier logic.

Rate Configuration

Main fields:

• Rate Source Type
• Rate Value
• Fixed Amount
• Balance Basis
• Day Count Convention
• Index Rate Code
• Spread / Margin

Typical use:

• fixed fee: use Fixed Amount
• percent-based item: use Rate Value
• indexed item: use Index Rate Code plus Spread / Margin

Field guidance:

• Rate Source Type: choose FIXED, INDEXED, TIERED, or NONE.
• Rate Value (%): use for percentage-based items when the line and handler support rate-based pricing.
• Fixed Amount: use for flat charges or returns.
• Balance Basis: matters for balance-driven pricing such as interest or balance-based fees.
• Day Count Convention: matters for time-based annualized pricing, especially interest-style items.
• Index Rate Code: used when the item references a managed rate index instead of a hardcoded rate.
• Spread / Margin: extra percentage added on top of the selected index rate.

Limits And Review

Main fields:

• Min Amount
• Max Amount
• Max Balance For Calc
• review frequency fields

Use these to cap or constrain the calculated result.

Field guidance:

• Min Amount: floor below which the calculated result cannot fall.
• Max Amount: cap above which the calculated result cannot rise.
• Max Balance For Calc: optional ceiling on the balance amount the handler can read.
• Review Frequency Unit and Review Frequency Interval: used for periodic review or repricing style behavior.

Lifecycle And Dates

Main fields:

• Active
• Effective From
• Effective To

Field guidance:

• Active: inactive items remain part of configuration history but are excluded from effective runtime resolution.
• Effective From and Effective To: control the date window in which the item is eligible to resolve and execute.

Posting Rule

The item can carry its own posting rule mapping.

Priority is:

1. item-level posting rule
2. profile-level fallback posting rule

If neither exists, the resolver will flag the item as missing a posting rule.

Important note:

• There is no pricing item field called value_text. If you see value_text elsewhere in Pinkapple, it belongs to other modules such as approval-condition or GL rule structures, not pricing item authoring. In GL approval policy conditions, for example, value_text is often used as a system code operand such as MANUAL, REVERSAL, UGX, or a rule code.
• The database still has a legacy is_tax_inclusive column on pricing_profile_item, but the pricing UI no longer authors it because it is not part of the current pricing-engine operating model.

System-Controlled Runtime Codes

Two pricing fields are especially important because they are runtime codes, not free prose:

• Trigger Transaction Type
• dependency Trigger State

The backend now validates both against controlled code sets.

That means:

• use the provided UI select values instead of typing approximations
• if an item is not transaction-driven, leave Trigger Transaction Type blank
• if a dependent item does not need a parent-state gate, leave dependency Trigger State blank
• invalid custom strings are rejected by the backend

Item Dependencies

Inside View Items, click Dependencies on an item row.

This opens the dependency dialog for that item.

Important:

• the item you opened is already the dependent child item
• you do not choose the child item again
• the main choice you make in the dialog is the parent/base item in Depends On Parent Item

Fields:

• Dependent Item
• Depends On Parent Item
• Dependency Type
• Parent Amount State
• Trigger State
• Execution Order
• Inherit Timing
• Inherit Settlement

Dependency Type Guidance

• Percent Of Parent: child amount is a rate of the parent amount
• Fixed Or Percent On Parent Trigger: child amount is fixed or percent-based off the parent-trigger context
• Tax On Parent: use for tax-like dependent items
• Penalty On Parent: use for penalty-style dependent items
• Commission On Parent: use for commission-style dependent items
• Discount On Parent: use for discount-style dependent items

Dependency Field Guidance

• Depends On Parent Item: the pricing item whose amount or state the child will read.
• Parent Amount State: which parent bucket the child should use, for example CALCULATED, DUE, OVERDUE, COLLECTED, or WAIVED.
• Trigger State: optional system parent-state gate. Use this when the child should only become eligible after the parent reaches a state such as OVERDUE, COLLECTED, WAIVED, or REVERSED.
• Execution Order: controls ordering when an item has more than one dependency or when you need deterministic sequencing among dependent items.
• Inherit Timing: use when the child should follow the parent item timing behavior instead of using its own independent timing setup.
• Inherit Settlement: use when the child should settle or allocate together with the parent item’s settlement lifecycle.

Supported trigger states are:

• CALCULATED
• ACCRUED
• DUE
• OUTSTANDING
• OVERDUE
• COLLECTED
• WAIVED
• REVERSED
• CAPITALIZED

Full Dependency Field Reference

Field	What it means	Engine implication
Dependent Item	The child item already scoped by the dialog you opened.	This is the item that will read from or react to the parent item.
Depends On Parent Item	The base item the child depends on.	Builds the graph edge the resolver uses for parent-before-child execution ordering.
Dependency Type	Semantic relationship such as TAX, PENALTY, DISCOUNT, PERCENT_OF_PARENT, or STATE_TRIGGER.	Tells the resolver and handler how to interpret the child-parent relationship.
Parent Amount State	The parent amount bucket to read, such as CALCULATED, DUE, OVERDUE, or COLLECTED.	Determines which monetary state from the parent drives the child item.
Trigger State	Optional system parent-state gate.	Prevents the child from becoming eligible until the parent reaches the selected state.
Execution Order	Numeric ordering for dependency evaluation.	Used to make sibling dependent-item sequencing deterministic.
Inherit Timing	Whether the child should follow the parent timing behavior.	Makes the child align with the parent’s due/accrual/application timing instead of acting independently.
Inherit Settlement	Whether the child should follow the parent settlement behavior.	Makes the child settle or close out with the parent lifecycle.
Effective From	Optional dependency-edge start date.	The dependency is ignored before this date.
Effective To	Optional dependency-edge end date.	The dependency is ignored after this date.
Active	Whether the dependency edge is enabled.	Inactive dependency links remain in history but are excluded from the resolved execution graph.

Important Rule

If an item depends on another item, configure the child item so its line code, handler, and rate model match that dependency semantics.

Example:

• a tax-on-parent item should use a tax-style line code
• a parent-based item should use a parent-aware calculation handler where required

Also note:

• a pricing item cannot depend on itself
• if you opened the dependency dialog from item A, then item A is already the child item and Depends On Parent Item must be some other item

Profile Links

From the profile row, click Profile Links.

Use this dialog to:

• include another profile
• control include order
• choose a conflict strategy

Conflict strategy matters when two profiles contribute the same pricing line code.

Bindings

From the profile row, click Bindings.

Use bindings to attach pricing to:

• account scope
• arrangement scope
• product scope
• segment scope
• business unit scope
• company scope
• system default scope
• optional channel and promotion qualifiers
• optional business unit and currency qualifiers

Bindings determine how the engine selects the root pricing profile for a real business target. The resolver ranks candidates from most specific to least specific, typically:

1. account
2. arrangement
3. product
4. segment
5. business unit
6. company
7. system default

Binding Field Reference

Field	What it means	Engine implication
Binding Type	PROFILE or PROFILE_ITEM.	PROFILE selects a whole pricing package as the root context; PROFILE_ITEM is a narrower special-case binding.
Binding Scope	Scope level such as account, arrangement, product, segment, business unit, company, or system.	Drives precedence in the resolver. More specific scopes beat more generic scopes.
Pricing Profile	Root pricing profile to attach.	Main package the resolver expands into effective items.
Pricing Item	Specific item reference for item-level binding scenarios.	Used only where item-level binding is intentionally supported.
Entity / Record	Concrete business target identifiers.	Used for exact record binding such as account-specific pricing.
Scope Code	Code-style qualifier for scopes such as segment or company.	Lets the resolver match non-record scope levels.
Channel Code	Optional channel qualifier.	Restricts eligibility to matching operational channels.
Promotion Code	Optional promotion qualifier.	Restricts eligibility to matching promotional context.
Business Unit	Optional BU qualifier.	Adds specificity and can break ties between otherwise similar bindings.
Currency	Optional currency qualifier.	Restricts the binding to matching currency context.
Priority	Explicit precedence inside similar candidates.	Used when multiple eligible bindings exist at the same scope and specificity.
Default	Marks a fallback binding inside the allowed scope.	Used as the conservative fallback when no more specific candidate wins.
Effective From / Effective To	Active date window for the binding.	Candidate is ignored outside this effective range.
Active	Whether the binding is currently enabled.	Inactive bindings stay in history but do not participate in live resolution.

Overrides

From the profile row, click Overrides.

Use overrides to modify inherited item behavior without cloning the full item.

Typical fields you may override:

• application mode
• rate source type
• rate value
• fixed amount
• min and max amount
• active state

Pricing Context Preview

From the profile row, click Preview Context.

This is the most important validation tool in the pricing UI.

It shows:

• root profile
• selected binding
• resolved profiles
• flattened items
• effective items
• dependencies
• conflicts
• validation findings
• dependency validation issues

How To Read The Preview

Summary

Use this tab to confirm:

• resolution source
• resolved profile count
• effective item count
• missing posting rule count
• dependency warning and error counts

Profiles

Use this tab to check the profile composition tree and inclusion path.

Items

Use this tab to compare:

• flattened items from all resolved profiles
• final effective items after conflict handling and overrides

Dependencies

Use this tab to inspect:

• child and parent item relationships
• dependency order
• dependency validation issues

Validation

Use this tab to review:

• generic validation errors
• generic validation warnings
• dependency-specific issues

Line Codes Tab

The Line Codes tab shows pricing line code master data.

It helps you inspect:

• component category
• owning module
• whether rate-based calculation is allowed
• whether fixed amount calculation is allowed

If a dependent pricing item is misclassified, the line code is usually the first place to verify.

Rate Indices Tab

The Rate Indices tab is used for indexed pricing.

Use it when an item should price from an external or managed index instead of a fixed rate.

When an approved rate index changes, the pricing engine now treats that as a repricing event for indexed items that reference that index. In practice that means:

• the new value is stored in rate history
• affected indexed pricing items are logged in the pricing rate-change log
• active pricing runtime schedules for those items are pushed forward so the new rate can be picked up on the next eligible run

Use manual repricing when you want to change the pricing item definition itself, for example:

• change a fixed rate
• change a fixed amount
• switch an item between FIXED and INDEXED
• change the spread or margin on an indexed item

Rate Index Maintenance Fields

Field	What it means	Engine implication
Index Code	Stable identifier for the managed rate index.	Referenced by indexed pricing items and pricing logs.
Index Name	Business-facing label of the index.	Used in admin UI and diagnostics.
Provider	Source of the published rate.	Audit and support context for the index.
Initial / Current Rate	Latest approved numeric value for the index.	Used by indexed pricing items on the next eligible runtime evaluation.
Active	Whether the index is currently enabled.	Inactive indices should not be used for new indexed pricing setup.

When you update a live rate index:

• the rate history row is updated or created for the day
• affected indexed pricing items are written to pricing_rate_change_log
• repricing metadata is preserved for audit
• runtime schedules for affected indexed items are pushed forward when needed

Common User Workflows

Add Pricing To A New Product

1. Create the pricing profile.
2. Add pricing items.
3. Add profile links if needed.
4. Add item dependencies if one item depends on another.
5. Attach posting rules.
6. Bind the profile to the correct target.
7. Run Preview Context.
8. Attach the profile from the product module.

Fix A Broken Dependent Item

1. Open the profile.
2. Open View Items.
3. Edit the child item.
4. Check the Line Code.
5. Check the Calculation Handler.
6. Check Rate Value or Fixed Amount.
7. Open Dependencies for that item.
8. Verify the dependency type and parent amount state.
9. Re-run Preview Context.

Diagnose Missing Posting Rules

1. Open Preview Context.
2. Check Missing Posting Rules.
3. Go back to View Items.
4. Add or correct the item-level posting rule.
5. If the item should inherit, verify the profile-level fallback mapping.
6. Refresh Preview Context.

Current UI Limitation

The Pricing UI fully supports:

• profile maintenance
• item maintenance
• profile links
• bindings
• overrides
• dependencies
• preview and validation

But line code editing may be restricted depending on the current admin setup. If you need a brand-new line code or a category change and the UI does not expose edit actions, that part may still need backend/admin-side support.

Failure And Batch Behavior

Pricing failures are fatal to the business activity that triggered them.

For single-origin domain actions such as:

• loan disbursement
• loan repayment pricing
• deposit transaction-triggered pricing

the origin action, pricing execution, and posting execution run in one transaction. If pricing or posting fails, the whole originating action rolls back.

For pricing batches such as:

• deposit EOD fee charging
• deposit interest accrual
• deposit interest capitalisation
• loan penalty assessment
• loan interest accrual

the batch now runs as one atomic unit for all accounts that are actually processed in that run.

• if one processed account fails pricing or posting, the whole batch rolls back
• successfully processed accounts from that same batch are not left committed
• accounts with no applicable pricing profile may still be skipped where the batch design intentionally ignores non-applicable accounts

Recommended Working Order

When building pricing, work in this order:

1. line codes
2. profiles
3. items
4. profile links
5. item dependencies
6. posting rules
7. bindings
8. overrides
9. preview context
10. product or account attachment

Related Guides

• GL Posting Rules
• GL Posting Approval