> ## Documentation Index
> Fetch the complete documentation index at: https://codebyahmed.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 |

<Note>
  `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.
</Note>

## 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.

<Warning>
  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.
</Warning>

<CodeGroup>
  ```typescript Display only (parseFloat) theme={null}
  // Safe for rendering, NOT for arithmetic
  const price = parseFloat(product.price); // e.g. 99.99
  console.log(`Price: $${price.toFixed(2)}`);
  ```

  ```typescript Arithmetic with Decimal.js theme={null}
  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
  ```

  ```typescript Sending money in a request body theme={null}
  // 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
  };
  ```
</CodeGroup>