Learning PathModule

High-precision pricing

Price below the smallest currency unit for bulk materials and commodities, and choose the rounding mode your invoicing requires.

Ask about this Page
Copy for LLM
View as Markdown

After completing this page, you should be able to:

  • Decide when a B2B price needs high precision rather than cent precision.

  • Configure a Standalone Price using HighPrecisionMoney.

  • Choose a Cart price-rounding mode appropriate for B2B invoicing.

Most prices fit neatly into the smallest unit of a currency: cents, for AUD or USD. B2B breaks that assumption. A distributor selling cabling, chemicals, or fasteners may price at a fraction of a cent per unit, then multiply by thousands of units per Line Item. If you store such a price rounded to the nearest cent, the rounding error multiplies with the quantity and the invoice total drifts. High-precision pricing exists for exactly this case.

Cent precision versus high precision

commercetools represents money in one of two forms:

  • CentPrecisionMoney stores an amount in the currency's standard minor units. For AUD, centAmount 129900 is AUD 1,299.00. This is the default and the right choice for almost all prices.
  • HighPrecisionMoney stores an amount as a fraction of the smallest indivisible unit, allowing more decimal places than the currency normally has. You use it when a per-unit price genuinely needs sub-cent accuracy.
HighPrecisionMoney uses preciseAmount and fractionDigits to represent sub-cent values. See HighPrecisionMoney for field constraints.
For example, to price a component at AUD 0.012345 each, you set fractionDigits to 6 and preciseAmount to 12345; that is, 12345 / 10^6 = 0.012345.
POST /{projectKey}/standalone-prices HTTP/1.1
Content-Type: application/json

{
  "sku": "ZET-CABLE-CAT6-METER",
  "channel": { "typeId": "channel", "key": "atlas-apac-pricing" },
  "value": {
    "type": "highPrecision",
    "currencyCode": "AUD",
    "preciseAmount": 12345,
    "fractionDigits": 6
  }
}
fractionDigits and the size of the integer part trade off against each other. preciseAmount is a 64-bit integer, so the more decimal places you reserve with fractionDigits, the smaller the maximum whole-currency amount you can represent. Choose the smallest fractionDigits that captures the precision your contract needs, rather than the maximum.

Rounding happens at the Cart

A high-precision unit price has to become a payable amount somewhere. That rounding is governed by the Cart's priceRoundingMode, which applies when a Line Item's price uses HighPrecisionMoney. The Cart's priceRoundingMode uses RoundingMode. For B2B invoices with many high-quantity lines, HalfEven is usually the safest default because it minimizes cumulative rounding bias. Choose another rounding mode only when a specific invoicing or regulatory requirement calls for it.

Worked example: an Atlas Corporate bulk order

Atlas Corporate's APAC division orders 12,500 meters of Cat6 cable priced at AUD 0.012345 per meter.

  • The unit price is stored as preciseAmount 12345 with fractionDigits 6.
  • The raw Line Item total is 12,500 × 0.012345 = AUD 154.3125.
  • With priceRoundingMode: HalfEven, the payable Line Item total rounds to AUD 154.31 (the third decimal, 2, rounds down).
Now compare the alternative: if the price had been stored as CentPrecisionMoney rounded to AUD 0.01 per meter, the Line Item would total 12,500 × 0.01 = AUD 125.00, an error of nearly AUD 30 on a single line, growing with every additional unit. High precision keeps the per-unit accuracy and defers a single rounding to the payable total, which is what a bulk B2B invoice requires.

Key takeaways

  • Use CentPrecisionMoney for ordinary prices; reach for HighPrecisionMoney only when a per-unit price needs sub-cent accuracy that multiplies across large quantities.
  • HighPrecisionMoney pairs preciseAmount with fractionDigits to store sub-cent values; check the API reference for field constraints.
  • Because preciseAmount is a 64-bit integer, more decimal places means a smaller maximum integer amount; use the smallest precision the contract needs.
  • The Cart's priceRoundingMode decides how a high-precision price becomes payable; use RoundingMode to check the available modes, and use HalfEven as the bias-minimizing default for B2B invoicing.

Test your knowledge