Money Values: Decimal String Format and Parsing Guide

Monetary values in the Ecommerce API use a decimal string format to avoid floating-point errors. Learn the format rules and how to parse values.

The Ecommerce API represents every monetary value as a decimal string rather than a JSON number. This design choice is intentional: IEEE 754 floating-point arithmetic — the kind JavaScript and most runtimes use for number — cannot exactly represent many decimal fractions. For example, 0.1 + 0.2 evaluates to 0.30000000000000004 in JavaScript. In financial contexts, those invisible rounding errors compound across calculations and produce incorrect totals. By sending money as a string, the API gives you the exact value and leaves the choice of precision library entirely to your application.

The Money Format

All price, cost, discount, and total fields use a decimal string that matches the pattern ^\d{1,10}(\.\d{1,2})?$. The integer portion can be up to 10 digits; the fractional portion, when present, must be exactly 1 or 2 digits. Values are always non-negative.

Valid examples:

"0"
"0.5"
"9.99"
"100.00"
"1499.9"
"9999999999.99"

Invalid examples — the API rejects these with a 400 error:

99.99          ← bare JSON number, not a string
"99.999"       ← more than 2 decimal places
"-5.00"        ← negative values are not allowed
"1,499.99"     ← comma separators are not accepted
""             ← empty string

Affected Fields

The following fields always carry a decimal string value. When you send them in a request body, format them as strings. When you read them from a response, parse them before performing arithmetic.

Field	Description
price	The base selling price of a product variant
cost_price	The wholesale / cost-of-goods price for a variant (admin only)
discount_percentage	Percentage discount applied to a variant’s price
total_amount	The total monetary value of an order
subtotal	The pre-discount, pre-tax line total in a cart or order
final_price	The computed selling price after applying the discount percentage

discount_percentage is a special decimal string bounded between "0.00" and "100.00". It follows the same string format but its valid range is 0–100 rather than an unbounded money amount. The API rejects values outside that range with a 400 validation error.

Parsing in Your App

When you read a monetary field from a response, convert it before doing any arithmetic. The safest approach is to use a dedicated decimal library. The example below shows both a quick parseFloat approach (acceptable for display-only use) and the recommended Decimal.js approach for any calculation.

Never use native JavaScript number arithmetic — +, -, *, / — directly on currency strings or on values obtained via parseFloat. Even a single multiplication can introduce a floating-point error that causes your displayed totals to diverge from the API’s authoritative values. Always use a decimal library such as Decimal.js, big.js, or dinero.js for any monetary calculation.

Display only (parseFloat)

// Safe for rendering, NOT for arithmetic
const price = parseFloat(product.price); // e.g. 99.99
console.log(`Price: $${price.toFixed(2)}`);