Part 020 — Monetary Precision, Currency Conversion, Rounding, Proration, and Tax Responsibility

Positioning

Monetary correctness gagal melalui detail kecil:

• float versus decimal;
• currency minor units;
• component versus total rounding;
• exchange-rate timestamp;
• partial-period proration;
• tax-inclusive versus tax-exclusive semantics;
• and allocation remainder.

Kesalahan satu sen dapat menjadi:

• reconciliation noise;
• invoice mismatch;
• revenue leakage;
• customer dispute;
• dan audit problem

ketika dikalikan jutaan transaksi.

Core thesis: money, currency, rounding, proration, dan tax boundaries harus dimodelkan sebagai explicit domain policies. Tidak ada “default arithmetic” yang aman untuk seluruh lifecycle.

1. Money Value Object

A Money value object should include:

amount
currency

Potential additional metadata:

• scale;
• rounding context;
• source;
• and effective time.

2. Decimal Arithmetic

Use decimal arithmetic for money.

Avoid binary floating-point types for authoritative amounts.

3. Precision

Precision is total number of digits.

4. Scale

Scale is number of fractional digits.

Example:

123.45
precision = 5
scale = 2

5. Currency Minor Unit

Different currencies may have:

• 0;
• 2;
• 3;
• or special cash rounding minor units.

Do not assume two decimals universally.

6. Internal Calculation Scale

Intermediate calculation may use more scale than final display.

7. Storage Scale

Storage scale should support:

• rates;
• allocations;
• and intermediate results.

Do not round too early.

8. Display Scale

Display may follow currency or product policy.

9. Contractual Scale

Contract may specify rate precision beyond currency minor unit.

Example:

• usage rate 0.000125 per event.

10. Amount versus Rate Precision

Rates may need higher precision than final charges.

11. Rounding

Rounding converts a high-precision value to allowed scale.

12. Rounding Modes

Common modes:

• HALF_UP;
• HALF_EVEN;
• HALF_DOWN;
• UP;
• DOWN;
• CEILING;
• FLOOR.

Select by domain policy.

13. HALF_UP

Common commercial expectation:

• 0.5 rounds away from zero.

14. HALF_EVEN

Banker’s rounding.

Can reduce aggregate bias.

15. UP

Rounds away from zero.

May systematically favor one party.

16. DOWN

Truncates toward zero.

17. CEILING and FLOOR

Direction depends on sign.

Use carefully for credits.

18. Rounding Policy

A policy must specify:

• mode;
• scale;
• stage;
• scope;
• and exception.

19. Rounding Stage

Possible stages:

• rate;
• quantity multiplication;
• adjustment;
• tax;
• component;
• subtotal;
• allocation;
• invoice total.

20. Early Rounding

Rounding early can accumulate error.

21. Late Rounding

Keeping high precision until total may conflict with invoice-line requirements.

22. Component Rounding

Each line/component is rounded independently.

23. Aggregate Rounding

Unrounded components are summed, then total rounded.

24. Component versus Aggregate Difference

Example:

3 components × 0.3333 = 0.9999

Component rounding to 0.33 each:

0.99

Total rounding:

1.00

Policy must decide.

25. Display Total Reconciliation

Displayed component sum should match displayed total or include explicit rounding adjustment.

26. Rounding Adjustment

A small explicit component can reconcile totals.

27. Remainder Allocation

Allocation of parent total may leave remainder.

28. Deterministic Remainder Rule

Possible rules:

• largest component;
• first stable component;
• designated primary line;
• or proportional residual.

Never use arbitrary list order.

29. Negative Amount Rounding

Credits and reversals must use policy that preserves expected symmetry.

30. Tax Rounding

Tax authority may require:

• per line;
• per invoice;
• or per tax group rounding.

31. Proration Rounding

Prorated amounts may need separate scale and final rounding.

32. Quantity Rounding

Measured usage or fractional quantity may have its own precision policy.

33. Currency

Currency is part of amount identity.

Never add money from different currencies directly.

34. Currency Code

Use stable code, typically ISO 4217 where applicable.

35. Transaction Currency

Currency of commercial commitment.

36. Contract Currency

Currency defined by agreement.

37. Billing Currency

Currency used for billing account/invoice.

38. Settlement Currency

Currency used for payment settlement.

39. Display Currency

A convenience for presentation.

It may not be binding.

40. Functional Currency

Finance/accounting may use an internal reporting currency.

41. Multi-Currency Quote

Possible models:

• one transaction currency per quote;
• multiple currencies by item;
• or one binding currency plus display conversions.

42. One-Currency-per-Quote

Simpler for:

• totals;
• approval;
• and acceptance.

43. Multi-Currency Complexity

Need:

• per-currency subtotals;
• conversion;
• and legal clarity.

44. Cross-Currency Total

Only valid with explicit exchange-rate conversion.

45. Currency Conversion

Conversion requires:

source currency
target currency
rate
rate source
effective time
conversion direction
rounding policy

46. Direct Rate

Example:

1 USD = 16000 IDR

47. Inverse Rate

Need consistent direction and precision.

48. Triangulation

Conversion may pass through intermediary currency.

Preserve route and rates.

49. Exchange-Rate Source

Possible sources:

• central bank;
• treasury;
• market provider;
• contract;
• or internal finance rate.

50. Exchange-Rate Type

Examples:

• spot;
• daily;
• monthly;
• contractual;
• and accounting rate.

51. Exchange-Rate Effective Time

Rate validity must be explicit.

52. Quote-Time Rate

Used to display or commit quote value.

53. Billing-Time Rate

May differ from quote-time rate.

Need policy.

54. Locked Rate

Commercial agreement may lock exchange rate.

55. Floating Rate

Billing may use rate at invoice or service date.

Quote should disclose uncertainty.

56. Conversion Provenance

Store:

• source;
• rate ID/version;
• timestamp;
• and original amount.

57. Conversion Rounding

Define scale and stage after conversion.

58. Double Conversion Risk

Avoid converting:

USD -> IDR -> USD

for authoritative comparison.

Keep original currency amount.

59. Display Conversion

A display conversion should be labeled indicative if non-binding.

60. Currency Mismatch

If quote and billing currencies differ, mapping must be explicit.

61. Exchange-Rate Failure

Possible behavior:

• incomplete price;
• use last valid rate with warning;
• manual review;
• or block.

62. Exchange-Rate Cache

Cache by:

• currency pair;
• rate type;
• and effective time.

63. Proration

Proration allocates a periodic charge over a partial period.

64. Proration Inputs

Need:

• full-period amount;
• period start;
• period end;
• service start/end;
• calendar policy;
• and rounding.

65. Proration Basis

Possible methods:

• actual days in period;
• fixed 30-day month;
• actual/actual;
• 30/360;
• hourly;
• no proration;
• and full-period billing.

66. Actual Days

Example:

monthly amount × active days / days in month

67. Fixed 30-Day

Every month treated as 30 days.

68. 30/360

Financial convention.

Use only if business policy requires.

69. Hourly Proration

Useful for cloud/usage-like subscriptions.

70. No Proration

Charge full period if active at any point or after cut-off.

71. Minimum Billable Period

Example:

• minimum one day;
• minimum one month;
• or minimum billing block.

72. Inclusive Day Semantics

Does activation day count?

Does termination day count?

Define explicitly.

73. Start-of-Day versus Instant

Activation at 15:00 can differ from date-only activation.

74. Timezone

Proration period depends on billing timezone.

75. Billing Cycle

Billing period may not align with calendar month.

76. Anniversary Cycle

Period starts on service anniversary.

77. First-Period Proration

Activation mid-cycle.

78. Last-Period Proration

Termination mid-cycle.

79. Mid-Cycle Upgrade

Requires:

• credit old charge;
• debit new charge;
• or delta charge.

80. Delta Proration

Example:

(new monthly - old monthly) × remaining fraction

81. Credit-and-Rebill

Alternative:

• reverse old partial amount;
• bill new partial amount.

82. Upgrade Effective Time

May be:

• request date;
• activation date;
• or scheduled date.

83. Downgrade Proration

May be delayed until next cycle due to policy.

84. Suspension Proration

Charge may:

• pause;
• reduce;
• or continue.

85. Resume Proration

Restart behavior must be defined.

86. Free Period and Proration

If activation occurs mid-month, determine whether free period counts:

• billing periods;
• calendar months;
• or elapsed duration.

87. Discount Proration

Discount may be prorated proportionally or applied fully.

88. Allowance Proration

Included usage allowance may be prorated for partial period.

89. Minimum Commitment and Proration

Minimum spend may not prorate.

90. Tax and Proration

Taxable basis follows prorated amount according to jurisdiction.

91. Proration Formula Provenance

Store:

• policy;
• dates;
• fraction;
• unrounded amount;
• and rounded result.

92. Proration Reproducibility

Use explicit calendar and timezone, not system defaults.

93. Tax Boundary

Tax responsibility may be split among:

• CPQ;
• tax engine;
• billing;
• invoicing;
• and finance.

94. Tax Estimate versus Authoritative Tax

Estimate

Used for quote preview.

Authoritative tax

Used for legal invoice.

Make status explicit.

95. Tax-Inclusive Pricing

Displayed price includes tax.

Need component extraction where required.

96. Tax-Exclusive Pricing

Tax added separately.

97. Tax-Exempt

Exemption may depend on:

• customer;
• certificate;
• product;
• jurisdiction;
• and date.

98. Tax Jurisdiction

May depend on:

• bill-to;
• sold-to;
• ship-to;
• service location;
• usage origin/destination;
• and legal entity.

99. Product Tax Classification

Product/charge needs tax category.

100. Charge Taxability

Different components may have different taxability.

Examples:

• subscription;
• equipment;
• installation;
• discount;
• and surcharge.

101. Tax Basis

Tax basis may be:

• pre-discount;
• post-discount;
• allocated amount;
• or jurisdiction-defined.

102. Discount and Tax

Some discounts reduce taxable basis; others may not.

Tax engine should own legal determination.

103. Surcharge and Tax

Surcharge may itself be taxable.

104. Fee versus Tax

Regulatory fee may be:

• provider fee;
• government tax;
• or pass-through charge.

Classify precisely.

105. Tax Rate

Needs:

• jurisdiction;
• category;
• effective date;
• and source.

106. Multiple Taxes

One component may have:

• national;
• regional;
• local;
• and special taxes.

107. Compound Tax

Tax may apply on top of another tax.

Order matters.

108. Tax Allocation

Bundle tax may need allocation across components.

109. Tax Rounding Scope

Possible:

• per line;
• per tax type;
• per jurisdiction;
• per invoice.

110. Tax Exemption Evidence

Store:

• certificate/reference;
• validity;
• and applicable scope.

111. Tax Address Validation

Incorrect address can produce incorrect jurisdiction.

112. Tax Service Request

Possible inputs:

seller legal entity
customer
bill-to
service location
product tax category
charge components
currency
effective date
tax-inclusive flag

113. Tax Service Response

Should include:

• tax components;
• jurisdiction;
• rate;
• taxable basis;
• status;
• and validity.

114. Tax Failure

Possible policy:

• quote without estimate;
• incomplete quote;
• manual review;
• or fallback.

115. Tax Timeout

Do not interpret as zero tax unless explicit policy permits.

116. Tax Cache

Tax rules can change.

Cache with:

• jurisdiction;
• category;
• date;
• and version.

117. Tax Recalculation

Triggers:

• address;
• product;
• quantity;
• discount;
• date;
• and legal entity changes.

118. Tax Snapshot

Quote may snapshot estimated tax.

Accepted quote should state whether tax is final or estimated.

119. Billing Tax

Billing/invoicing may recalculate authoritative tax.

120. Quote-to-Invoice Variance

Tax variance can be legitimate if:

• estimate;
• date changed;
• usage changed;
• or jurisdiction changed.

121. Tax Reconciliation

Compare:

• quote estimate;
• order tax instruction;
• invoiced tax;
• and explanation.

122. Tax Correction

Invoice tax correction may require:

• credit note;
• rebill;
• and audit.

123. Monetary Invariants

Representative invariants:

• every amount has currency;
• no direct cross-currency addition;
• rounding policy is explicit;
• displayed totals reconcile;
• proration fraction is bounded;
• tax components have basis and jurisdiction;
• and accepted monetary snapshot is immutable.

124. Cross-Service Monetary Consistency

Services must agree on:

• currency;
• scale;
• rounding mode;
• and component identity.

125. Shared Money Library

A shared library can enforce basic value semantics.

It should not centralize all commercial policy.

126. Contract-Level Monetary Policy

A contract may define:

• currency;
• rounding;
• exchange rate;
• and proration.

127. Market-Level Monetary Policy

Market may define:

• default currency;
• display scale;
• and tax presentation.

128. Billing-Level Monetary Policy

Billing may define invoice rounding and cycle proration.

129. Policy Precedence

Need explicit precedence among:

• regulatory;
• contract;
• market;
• product;
• and billing policies.

130. Monetary Policy Version

Store version for reproducibility.

131. Money Serialization

API should serialize decimal as exact decimal representation.

Avoid conversion to binary float in clients.

132. String versus Number JSON

Both have trade-offs.

Contract must specify precision-safe behavior.

133. Database Storage

Use exact decimal/numeric type or integer minor units where semantics permit.

134. Integer Minor Units

Useful for final currency amounts.

Less suitable for high-precision rates without scaling metadata.

135. Decimal Columns

Need consistent precision/scale across services.

136. Overflow

Validate maximum amount and quantity.

137. Sign Semantics

Positive/negative meaning should be consistent for:

• charge;
• discount;
• credit;
• and reversal.

138. Null versus Zero

Zero is a valid amount.

Null/missing means no value.

139. Unknown Tax

Unknown is not zero.

140. Indicative Currency Conversion

Mark non-binding conversion clearly.

141. Partial Monetary Result

Some components may be priced while tax is pending.

Status should reflect partial result.

142. Audit Trail

Store:

• original inputs;
• policies;
• intermediate values;
• and final result.

143. Calculation Trace

Trace should include:

• unrounded;
• rounded;
• allocation;
• conversion;
• proration;
• and tax basis.

144. Trace Security

Tax and pricing traces may contain sensitive commercial data.

145. Rounding Test Matrix

Test:

• positive;
• negative;
• exact half;
• just below;
• just above;
• and large values.

146. Currency Test Matrix

Test:

• 0-decimal;
• 2-decimal;
• 3-decimal;
• high-precision rates;
• and conversion.

147. Proration Test Matrix

Test:

• first day;
• last day;
• mid-period;
• leap year;
• February;
• timezone transition;
• and zero active duration.

148. Tax Test Matrix

Test:

• inclusive/exclusive;
• exempt;
• multiple taxes;
• discount;
• surcharge;
• and rounding.

149. Property-Based Testing

Properties:

• allocation components sum to parent total;
• no cross-currency sum without conversion;
• proration never exceeds full charge unless policy says so;
• conversion round-trip stays within tolerance;
• and displayed totals reconcile.

150. Golden Monetary Scenarios

Maintain representative cases for:

• currency;
• rounding;
• proration;
• discount;
• and tax.

151. Differential Testing

Compare current and candidate monetary policy.

152. Billing Reconciliation Test

Verify quote/order/billing use compatible semantics.

153. Monetary Observability

Metrics:

• rounding adjustment frequency;
• quote-to-bill variance;
• exchange-rate fallback;
• tax failure;
• proration disputes;
• and unreconciled totals.

154. Alerting

Alert on:

• non-zero unexplained variance;
• missing currency;
• invalid rate;
• negative tax basis;
• and duplicate rounding adjustments.

155. Monetary Incident

Examples:

• float precision issue;
• different rounding between services;
• wrong exchange-rate date;
• double proration;
• and tax estimate treated as final.

156. Incident Analysis

Ask:

Which amount?
Which currency?
Which policy/version?
At what stage was rounding applied?
Which period and timezone?
Which tax basis?

157. Reconciliation Record

Should include:

• quote amount;
• order amount;
• billed amount;
• allowed tolerance;
• reason;
• and owner.

158. Tolerance

Tolerance should be policy-based.

Do not hide systematic errors under broad tolerance.

159. Rounding Smells

• every service rounds independently;
• mode unspecified;
• and totals patched manually.

160. Currency Smells

• currency inferred from tenant;
• rate timestamp missing;
• and display conversion stored as binding amount.

161. Proration Smells

• month assumed 30 days;
• timezone implicit;
• activation/termination inclusivity undefined;
• and discount proration guessed.

162. Tax Smells

• tax as one generic percentage;
• timeout means zero;
• jurisdiction not stored;
• and quote estimate called final.

163. Anti-Patterns

Double for Money

Precision defect.

Two Decimal Places Everywhere

Currency/rate semantics ignored.

Round at Every Step

Accumulated bias.

Convert and Forget Original

Audit lost.

Proration in UI

Authoritative logic duplicated.

Tax Logic in Product Code

Legal policy becomes scattered.

Tax Zero on Failure

Customer and compliance risk.

164. Monetary Policy Template

## Policy ID and Version

## Scope

## Currency Rules

## Internal Precision

## Display Precision

## Rounding Mode

## Rounding Stages

## Allocation Remainder

## Proration Basis

## Timezone / Calendar

## Tax Boundary

## Tolerance

## Ownership

165. Currency Conversion Template

Source amount:
Source currency:
Target currency:
Rate:
Direction:
Rate source:
Effective time:
Intermediate amount:
Rounding policy:
Converted amount:
Binding or indicative:

166. Proration Template

Full-period amount:
Currency:
Period start:
Period end:
Active start:
Active end:
Timezone:
Basis:
Numerator:
Denominator:
Unrounded amount:
Rounded amount:
Policy/version:

167. Tax Component Template

Tax ID/type:
Jurisdiction:
Rate:
Taxable basis:
Currency:
Inclusive/exclusive:
Exemption:
Source:
Validity:
Estimated/final:
Rounded amount:

168. Allocation Template

Parent amount:
Target components:
Allocation weights:
Unrounded allocations:
Rounded allocations:
Remainder:
Remainder owner:
Policy/version:

169. Worked Example: Component Rounding

Three components each:

• 0.3333.

Policy A, line rounding:

• 0.33 + 0.33 + 0.33 = 0.99.

Policy B, total rounding:

• total = 1.00.

Choose and preserve policy.

170. Worked Example: Bundle Allocation

Bundle total:

• 100.00.

Weights:

• 50%;
• 30%;
• 20%.

Allocated:

• 50.00;
• 30.00;
• 20.00.

If fractions create remainder, assign deterministically.

171. Worked Example: Zero-Decimal Currency

A currency with zero minor digits requires whole-unit display.

High-precision internal rates may still be needed before final charge.

172. Worked Example: Exchange Rate

Quote:

• 100 USD.

Display:

• 1,600,000 IDR using 16,000 rate.

Store:

• original 100 USD;
• rate source/time;
• converted display amount;
• binding currency status.

173. Worked Example: First-Period Proration

Monthly charge:

Billing cycle:

• 1–31.

Activation:

• day 16.

Actual-days policy:

• active 16 days out of 31;
• unrounded = 51.6129...;
• rounded according to policy.

174. Worked Example: Mid-Cycle Upgrade

Old monthly:

New monthly:

Upgrade halfway through cycle.

Delta method:

• 60 × remaining fraction.

Credit-and-rebill method may yield same or slightly different rounded result.

Policy decides.

175. Worked Example: Discount and Proration

Base monthly:

Discount:

• 20%.

Active half month.

Possible result:

100 × 50% × 80% = 40

Order of calculation and rounding must be explicit.

176. Worked Example: Tax Estimate

Net recurring:

Tax estimate:

• 11%.

Result:

• 11 tax;
• 111 gross.

Store:

• jurisdiction;
• taxable basis;
• estimate status;
• and source.

177. Worked Example: Tax-Inclusive Price

Gross price:

Tax rate:

• 11%.

Extracting net/tax requires jurisdiction-approved formula and rounding.

Do not use naive subtraction without policy.

178. Worked Example: Tax Failure

Tax provider times out.

Correct behavior may be:

• price complete but tax pending;
• quote marked estimate unavailable;
• or presentation blocked.

Incorrect:

• tax = 0 without warning.

179. Worked Example: Quote-to-Bill Variance

Quote tax was estimate.

Invoice tax differs by 0.02 due to invoice-level rounding.

Reconciliation classifies:

• expected policy variance;
• not unexplained defect.

180. Senior Engineer Operating Model

Standardize Money semantics

Exact decimal, explicit currency.

Define every rounding stage

No implicit defaults.

Preserve unrounded and rounded values where needed

Support audit and reconciliation.

Keep original currency

Converted display is not replacement.

Treat proration as policy

Calendar, timezone, inclusivity, and basis.

Separate tax estimate from final tax

Boundary and responsibility must be clear.

Test pathological boundaries

Half values, month ends, leap years, and negative amounts.

Reconcile across systems

Quote, order, billing, and invoice.

Version monetary policy

Semantics evolve.

181. Internal Verification Checklist

Money

• Which numeric types are used?
• What precision/scale exists?
• Are rates and final amounts modeled differently?
• How are signs represented?

Currency

• Is one currency enforced per quote?
• What are contract, billing, and display currencies?
• Who owns exchange rates?
• Are original and converted amounts preserved?

Rounding

• What mode is used?
• At which stages?
• Is rounding per line or total?
• How is allocation remainder handled?

Proration

• Which basis is used?
• What timezone/calendar applies?
• Are activation/termination days inclusive?
• How do upgrades, discounts, and allowances prorate?

Tax

• Is tax quote-time estimate or final?
• Who owns tax policy?
• What jurisdiction inputs are required?
• What happens on timeout/failure?

Integration

• Do pricing and billing use compatible policies?
• Are monetary policy versions passed?
• Can one calculation be replayed?
• How is quote-to-invoice variance classified?

Operations

• What tolerance is allowed?
• Are rounding/proration/tax mismatches monitored?
• Can support inspect calculation traces?
• What historical incidents reveal policy gaps?

182. Practical Exercises

Exercise 1 — Money type audit

Find every float/double or unqualified decimal used for money.

Exercise 2 — Rounding matrix

Document rounding mode and stage for components, totals, allocation, tax, and invoice.

Exercise 3 — Currency flow

Trace original, display, billing, and settlement currencies.

Exercise 4 — Proration scenarios

Calculate activation, termination, suspension, and upgrade cases.

Exercise 5 — Tax boundary

Map which system estimates and which system finalizes tax.

Exercise 6 — Reconciliation

Define allowed and unexplained variance categories.

183. Part Completion Checklist

You are done if you can:

• model exact Money values;
• define precision and scale;
• select explicit rounding modes and stages;
• reconcile component and total rounding;
• perform currency conversion with provenance;
• distinguish binding and display currencies;
• define proration basis and calendar semantics;
• separate tax estimate from authoritative tax;
• test monetary edge cases;
• and create an internal monetary-policy verification backlog.

184. Key Takeaways

1. Money requires exact arithmetic.
2. Currency is part of amount identity.
3. Rates may need more precision than final amounts.
4. Rounding mode, scale, stage, and scope must be explicit.
5. Component and total rounding can differ.
6. Original currency must be preserved.
7. Proration is a business policy, not a generic formula.
8. Tax estimate and final invoice tax differ.
9. Unknown tax is not zero.
10. Internal CSG monetary and tax boundaries must be verified.

185. References

Conceptual baseline:

• General money, decimal arithmetic, currency, exchange-rate, and rounding practices.
• Subscription billing, calendar periods, proration, and charge-allocation concepts.
• Tax-estimation versus invoice-tax boundaries and jurisdictional calculation concepts.
• Domain-Driven Design value objects, immutable monetary snapshots, and auditability.

These references do not define internal CSG currency, proration, rounding, or tax policy.