@spree/docs 0.1.97 → 0.1.99
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -4,7 +4,7 @@ sidebarTitle: "Monetary Amounts"
|
|
|
4
4
|
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."
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
All monetary values in the Admin API are **strings** (e.g., `"29.99"`, `"0.0"`), both in responses and in request bodies.
|
|
7
|
+
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)).
|
|
8
8
|
|
|
9
9
|
## Reading
|
|
10
10
|
|
|
@@ -40,24 +40,11 @@ spree api post /products -d '{"name":"Classic Tee","prices":[{"currency":"USD","
|
|
|
40
40
|
|
|
41
41
|
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.
|
|
42
42
|
|
|
43
|
-
###
|
|
43
|
+
### Canonical format — not localized
|
|
44
44
|
|
|
45
|
-
Amounts
|
|
45
|
+
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"`.
|
|
46
46
|
|
|
47
|
-
|
|
48
|
-
```typescript Admin SDK
|
|
49
|
-
await client.products.create({
|
|
50
|
-
name: 'Designer Bag',
|
|
51
|
-
prices: [{ currency: 'EUR', amount: '1.299,00' }],
|
|
52
|
-
})
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
```bash CLI
|
|
56
|
-
spree api post /products -d '{"name":"Designer Bag","prices":[{"currency":"EUR","amount":"1.299,00"}]}'
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
Only the string form can express a localized amount — a JSON number literal cannot represent `1.299,00`.
|
|
47
|
+
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).
|
|
61
48
|
|
|
62
49
|
## Affected types
|
|
63
50
|
|
|
@@ -77,7 +64,7 @@ This convention applies to all monetary fields across all resources, including b
|
|
|
77
64
|
|
|
78
65
|
### Amounts inside `preferences`
|
|
79
66
|
|
|
80
|
-
Calculators and some promotion rules carry their amounts inside an untyped `preferences` object (`Record<string, unknown>`) rather than as top-level fields. The same string convention applies to the money-valued keys within that hash — they read back as strings and accept
|
|
67
|
+
Calculators and some promotion rules carry their amounts inside an untyped `preferences` object (`Record<string, unknown>`) rather than as top-level fields. The same canonical-string convention applies to the money-valued keys within that hash — they read back as strings and accept canonical decimal strings on write. The keys that are money:
|
|
81
68
|
|
|
82
69
|
| Resource | Money keys in `preferences` |
|
|
83
70
|
|----------|------------------------------|
|