0
# Amount Utilities
1
2
Currency-aware financial calculation utilities for converting between human-readable display formats and database storage formats, with proper handling of zero-decimal currencies.
3
4
## Capabilities
5
6
### Amount Computerization
7
8
Converts human-readable amounts to database storage format (typically cents for most currencies).
9
10
```typescript { .api }
11
/**
12
* Converts a display amount to database storage format
13
* @param amount - The display amount (e.g., 19.99)
14
* @param currency - The currency code (e.g., "USD", "EUR", "JPY")
15
* @returns The amount in database format (e.g., 1999 for $19.99)
16
*/
17
function computerizeAmount(amount: number, currency: string): number;
18
```
19
20
**Usage Examples:**
21
22
```typescript
23
import { computerizeAmount } from "medusa-core-utils";
24
25
// Regular currencies (2 decimal places)
26
const usdAmount = computerizeAmount(19.99, "USD"); // 1999 (cents)
27
const eurAmount = computerizeAmount(25.50, "EUR"); // 2550 (cents)
28
29
// Zero-decimal currencies
30
const jpyAmount = computerizeAmount(1000, "JPY"); // 1000 (no conversion)
31
const krwAmount = computerizeAmount(50000, "KRW"); // 50000 (no conversion)
32
33
// Store in database
34
const product = {
35
name: "T-Shirt",
36
price: computerizeAmount(29.99, "USD"), // Stored as 2999
37
currency: "USD"
38
};
39
```
40
41
### Amount Humanization
42
43
Converts database storage amounts back to human-readable display format.
44
45
```typescript { .api }
46
/**
47
* Converts a database amount to display format
48
* @param amount - The database amount (e.g., 1999)
49
* @param currency - The currency code (e.g., "USD", "EUR", "JPY")
50
* @returns The display amount (e.g., 19.99 for 1999 cents)
51
*/
52
function humanizeAmount(amount: number, currency: string): number;
53
```
54
55
**Usage Examples:**
56
57
```typescript
58
import { humanizeAmount } from "medusa-core-utils";
59
60
// Regular currencies (divide by 100)
61
const displayUSD = humanizeAmount(1999, "USD"); // 19.99
62
const displayEUR = humanizeAmount(2550, "EUR"); // 25.50
63
64
// Zero-decimal currencies (no conversion)
65
const displayJPY = humanizeAmount(1000, "JPY"); // 1000
66
const displayKRW = humanizeAmount(50000, "KRW"); // 50000
67
68
// Display in UI
69
const product = await getProduct(id);
70
const displayPrice = humanizeAmount(product.price, product.currency);
71
console.log(`Price: ${displayPrice} ${product.currency}`);
72
```
73
74
### Zero-Decimal Currencies
75
76
List of currencies that do not use decimal places in their smallest unit.
77
78
```typescript { .api }
79
/**
80
* Array of currency codes that use zero decimal places
81
* These currencies are not divided by 100 during conversion
82
*/
83
const zeroDecimalCurrencies: string[];
84
```
85
86
The zero-decimal currencies include:
87
88
- **BIF** - Burundian Franc
89
- **CLP** - Chilean Peso
90
- **DJF** - Djiboutian Franc
91
- **GNF** - Guinean Franc
92
- **JPY** - Japanese Yen
93
- **KMF** - Comorian Franc
94
- **KRW** - South Korean Won
95
- **MGA** - Malagasy Ariary
96
- **PYG** - Paraguayan Guaraní
97
- **RWF** - Rwandan Franc
98
- **UGX** - Ugandan Shilling
99
- **VND** - Vietnamese Đồng
100
- **VUV** - Vanuatu Vatu
101
- **XAF** - Central African CFA Franc
102
- **XOF** - West African CFA Franc
103
- **XPF** - CFP Franc
104
105
**Usage Examples:**
106
107
```typescript
108
import { zeroDecimalCurrencies, computerizeAmount, humanizeAmount } from "medusa-core-utils";
109
110
// Check if currency is zero-decimal
111
function isZeroDecimalCurrency(currency: string): boolean {
112
return zeroDecimalCurrencies.includes(currency.toLowerCase());
113
}
114
115
// Comprehensive amount handling
116
function processAmount(amount: number, currency: string) {
117
const isZeroDecimal = isZeroDecimalCurrency(currency);
118
119
if (isZeroDecimal) {
120
console.log(`${currency} is a zero-decimal currency`);
121
}
122
123
const dbAmount = computerizeAmount(amount, currency);
124
const displayAmount = humanizeAmount(dbAmount, currency);
125
126
return {
127
original: amount,
128
database: dbAmount,
129
display: displayAmount,
130
isZeroDecimal
131
};
132
}
133
134
// Examples
135
processAmount(100, "JPY"); // { original: 100, database: 100, display: 100, isZeroDecimal: true }
136
processAmount(100, "USD"); // { original: 100, database: 10000, display: 100, isZeroDecimal: false }
137
```
138
139
### Complete Amount Processing Workflow
140
141
**Usage Examples:**
142
143
```typescript
144
import { computerizeAmount, humanizeAmount, zeroDecimalCurrencies } from "medusa-core-utils";
145
146
// Product creation workflow
147
async function createProduct(productData: {
148
name: string;
149
price: number;
150
currency: string;
151
}) {
152
// Convert display price to database format
153
const dbPrice = computerizeAmount(productData.price, productData.currency);
154
155
const product = await database.products.create({
156
name: productData.name,
157
price: dbPrice, // Stored in cents (or whole units for zero-decimal)
158
currency: productData.currency.toUpperCase()
159
});
160
161
return product;
162
}
163
164
// Product display workflow
165
async function getProductForDisplay(productId: string) {
166
const product = await database.products.findById(productId);
167
168
// Convert database price to display format
169
const displayPrice = humanizeAmount(product.price, product.currency);
170
171
return {
172
...product,
173
displayPrice,
174
formattedPrice: `${displayPrice} ${product.currency}`
175
};
176
}
177
178
// Bulk price calculations
179
function calculateTotals(items: Array<{price: number, currency: string, quantity: number}>) {
180
return items.map(item => {
181
const unitPrice = humanizeAmount(item.price, item.currency);
182
const lineTotal = unitPrice * item.quantity;
183
const lineTotalDb = computerizeAmount(lineTotal, item.currency);
184
185
return {
186
...item,
187
unitPrice,
188
lineTotal,
189
lineTotalDb
190
};
191
});
192
}