Money Values: Decimal String Format and Parsing Guide

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.

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

import Decimal from "decimal.js";

const price = new Decimal(variant.price);           // "29.99"
const discountPct = new Decimal(variant.discount_percentage); // "10.00"

const multiplier = new Decimal(1).minus(discountPct.div(100));
const finalPrice = price.times(multiplier);

console.log(finalPrice.toFixed(2)); // "26.99" — exact, no floating-point drift

// Summing line items in a cart
const lineTotal = new Decimal(item.price).times(item.quantity);
const subtotal = lineItems.reduce(
  (acc, item) => acc.plus(new Decimal(item.price).times(item.quantity)),
  new Decimal("0")
);

console.log(subtotal.toFixed(2)); // exact total

// Always send money as a string in request bodies
const payload = {
  price: "49.99",           // ✅ string
  cost_price: "22.50",      // ✅ string
  discount_percentage: "15.00", // ✅ string, 0–100
};

// If you computed the value with Decimal.js, serialise it like this:
const computedPrice = new Decimal("45.00");
const body = {
  price: computedPrice.toFixed(2), // "45.00" — always a string
};

Get Started

Core Concepts

Money Values: Decimal String Format and Parsing Guide

The Money Format

Affected Fields

Parsing in Your App

​The Money Format

​Affected Fields

​Parsing in Your App

The Money Format

Affected Fields

Parsing in Your App