@spree/docs 0.1.303 → 0.1.304

package/dist/api-reference/admin-api/monetary-amounts.md

@@ -4,7 +4,7 @@ sidebarTitle: "Monetary Amounts"
 description: "How the Admin API represents money as decimal strings, why JSON numbers are avoided, and how to send prices, costs, and amounts safely in requests."
 ---
 
-All monetary values in the Admin API are **canonical decimal strings** (e.g., `"29.99"`, `"0.0"` — period decimal, no thousands grouping), both in responses and in request bodies. Strings preserve decimal precision and avoid the floating-point rounding issues common with JSON numbers — critical when an admin is setting prices and costs. The format is the same regardless of locale; localized formatting is a presentation concern handled by the client (see [Canonical format](#canonical-format-not-localized)).
+All monetary values in the Admin API are **canonical decimal strings** (period decimal, no thousands grouping), both in responses and in request bodies. Responses write each amount with exactly its currency's decimal places — `"29.99"` in USD, `"1.500"` in Kuwaiti dinar, `"1000"` in yen — and unit prices (`price`, `amount` on a price, `compare_at_amount`, `cost_price`, `unit_cost`) with up to four (`"0.0125"`). A currency's decimal places are its `decimal_places`, from ISO 4217. Strings preserve decimal precision and avoid the floating-point rounding issues common with JSON numbers — critical when an admin is setting prices and costs. The format is the same regardless of locale; localized formatting is a presentation concern handled by the client (see [Canonical format](#canonical-format-not-localized)).
 
 ## Reading
 
@@ -19,7 +19,7 @@ Every monetary field is returned as a string, alongside a `display_` companion t
 }
 ```
 
-Use `display_*` for rendering and the raw string fields for calculations (`parseFloat(price.amount)`).
+Use `display_*` for rendering and the raw string fields for calculations, with a decimal library rather than `parseFloat`. The SDK exports `sumMoney`, `subtractMoney`, `multiplyMoney`, `compareMoney` and `isZeroMoney`, which work on the strings exactly.
 
 ## Writing
 
@@ -38,13 +38,25 @@ spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","
 ```
 
 
-JSON numbers are also accepted (`"amount": 29.99`), but strings are recommended: they round-trip with what the API returns and sidestep float precision. A `null` clears the value.
+Only strings are accepted. A JSON number (`"amount": 29.99`), a localized or grouped string (`"1.234,56"`, `"1,234.56"`), or more decimals than the field holds (`"19.999"` in USD, `"100.5"` in yen; unit prices allow four) is refused with `422` and the error code `invalid_money_format`, naming the field:
+
+```json
+{
+  "error": {
+    "code": "invalid_money_format",
+    "message": "amount must be a decimal string like \"19.99\"",
+    "details": { "amount": ["must be a decimal string like \"19.99\""] }
+  }
+}
+```
+
+A `null` clears the value.
 
 ### Canonical format — not localized
 
 Amounts are **canonical**: a period decimal separator and no thousands grouping (`"1234.56"`), independent of any locale. The Admin API does **not** parse locale-specific formats — do not send `"1.234,56"` or `"1,234.56"`.
 
-If you are taking input from a merchant in a localized format, normalize it to canonical form **before** sending. The Spree dashboard does this in the browser: a EUR price typed as `1.234,56` becomes `1234.56` on the wire. This matches how other commerce APIs handle money (canonical decimal or minor-unit integers; localization is a presentation concern).
+If you are taking input from a merchant in a localized format, normalize it to canonical form **before** sending. The Spree dashboard does this in the browser, in the number format of the person using it: an admin who writes German types `1.234,56`, in any currency, and `1234.56` goes on the wire. This matches how other commerce APIs handle money (canonical decimal or minor-unit integers; localization is a presentation concern).
 
 ## Affected types
 
@@ -75,4 +87,8 @@ Calculators and some promotion rules carry their amounts inside an untyped `pref
 | **Calculator** `flat_rate` (shipping) | `amount`, `minimum_item_total`, `maximum_item_total` |
 | **Promotion Rule** `item_total` | `amount_min`, `amount_max` |
 
-Percentage keys (`percent`, `flat_percent`, `base_percent`), weights (`minimum_weight`, `maximum_weight`), and quantities (`max_items`, `min_quantity`) are **not** money — those stay numbers. Promotion actions (`create_adjustment`, `create_item_adjustments`) hold their money inside a nested `calculator.preferences`, per the calculator rows above.
+Percentage keys (`percent`, `flat_percent`, `base_percent`) are rates: decimal strings too (`"10"`), with no fixed number of decimals. Weights (`minimum_weight`, `maximum_weight`) and quantities (`max_items`, `min_quantity`) are not money and stay numbers. Promotion actions (`create_adjustment`, `create_item_adjustments`) hold their money inside a nested `calculator.preferences`, per the calculator rows above.
+
+## Rates and percentages
+
+Rates and percentages are decimal strings without trailing zeros, on read and write. A field ending in `_percent` or `_percentage` holds 0–100 (`"23"`); a field named `rate` or ending in `_rate` holds a fraction (`"0.23"`). A tax rate has both: `rate` and `rate_percent`, and accepts either on write.

package/dist/api-reference/store-api/monetary-amounts.md

@@ -4,7 +4,7 @@ sidebarTitle: "Monetary Amounts"
 description: "How monetary values are represented in API responses"
 ---
 
-All monetary values in the Store API are returned as **strings** (e.g., `"29.99"`, `"0.0"`), not numbers. This preserves decimal precision and avoids floating-point rounding issues common with JSON numbers.
+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](#currency-decimal-places)).
 
 ## Response Format
 
@@ -35,7 +35,13 @@ This convention applies to all monetary fields across all resources:
 | **Payment** | `amount` |
 | **Gift Card** | `amount`, `amount_used`, `amount_authorized`, `amount_remaining` |
 | **Store Credit** | `amount`, `amount_used`, `amount_remaining` |
-| **Price** | `amount`, `compare_at_amount` |
+| **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
 
@@ -43,12 +49,15 @@ This convention applies to all monetary fields across all resources:
 ```typescript SDK
 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"
 
-// Convert to number for calculations
-const total = parseFloat(order.total);
+// 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;
 ```
 
 ```javascript JavaScript
@@ -57,9 +66,9 @@ const data = await response.json();
 // Use display fields for rendering
 element.textContent = data.display_total; // "$129.99"
 
-// Use raw fields for calculations
-const total = parseFloat(data.total);
+// Calculate on the raw strings with a decimal library, never parseFloat:
+// 0.1 + 0.2 is 0.30000000000000004 as a JSON number.
 ```
 
 
-> **TIP:** 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. Use the raw string fields when you need to perform calculations.
+> **TIP:** 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.