Monetary Amounts

All monetary values in the Store API are returned as decimal strings, never JSON numbers, written with exactly the decimal places of their currency: "29.99" in USD, "1.500" in Kuwaiti dinar, "1000" in yen. Unit prices may carry up to four decimals ("0.0125"). This preserves decimal precision and avoids the rounding errors of JSON numbers. A currency’s decimal places are its decimal_places (see below).

Response Format

Every monetary field has a corresponding display_ field that includes currency formatting:

{
  "total": "129.99",
  "display_total": "$129.99",
  "item_total": "99.99",
  "display_item_total": "$99.99",
  "delivery_total": "10.00",
  "display_delivery_total": "$10.00",
  "tax_total": "20.00",
  "display_tax_total": "$20.00"
}

Affected Types

This convention applies to all monetary fields across all resources:

Resource	Monetary Fields
Cart / Order	`total`, `item_total`, `delivery_total`, `tax_total`, `adjustment_total`, `discount_total`, `included_tax_total`, `additional_tax_total`, `fee_total`, `store_credit_total`, `gift_card_total`, `amount_due`
Line Item	`price`, `total`, `adjustment_total`, `discount_total`, `included_tax_total`, `additional_tax_total`, `pre_tax_amount`, `discounted_amount`, `compare_at_amount`
Fulfillment	`cost`
Payment	`amount`
Gift Card	`amount`, `amount_used`, `amount_authorized`, `amount_remaining`
Store Credit	`amount`, `amount_used`, `amount_remaining`
Price	`amount`, `compare_at_amount` (unit prices, up to four decimals)

Rates, such as a tax line’s rate, are decimal strings too, without trailing zeros ("0.23").

Currency decimal places

Each currency the store sells in (GET /api/v3/store/currencies) carries decimal_places, from ISO 4217: 2 for USD and EUR, 0 for JPY, 3 for KWD. Every amount in that currency is written with that many decimals.

Working with Amounts

const order = await client.orders.get('or_abc123', {}, { token });

import { compareMoney, sumMoney } from '@spree/sdk'

// Raw string values
order.total;         // "129.99"
order.display_total; // "$129.99"

// Calculate on the strings, exactly
const subtotal = sumMoney(order.items.map((item) => item.total), order.currency); // "129.99"
const isFree = compareMoney(order.total, '0') === 0;

const data = await response.json();

// Use display fields for rendering
element.textContent = data.display_total; // "$129.99"

// Calculate on the raw strings with a decimal library, never parseFloat:
// 0.1 + 0.2 is 0.30000000000000004 as a JSON number.

Use display_* fields for rendering prices in the UI — they are pre-formatted with the correct currency symbol and decimal places based on the order’s currency. Calculate on the raw strings with the SDK’s sumMoney, subtractMoney, multiplyMoney and compareMoney, which work on decimal strings exactly.

API basics

Endpoints

Response Format

Affected Types

Currency decimal places

Working with Amounts

​Response Format

​Affected Types

​Currency decimal places

​Working with Amounts

Response Format

Affected Types

Currency decimal places

Working with Amounts