MonetaryAmount
Represents a monetary value with its associated currency, ensuring that amounts are always paired with their currency context to prevent errors and ambiguity. This entity implements the Money pattern from domain-driven design, treating amount and currency as an inseparable pair. It supports financial calculations, multi-currency operations, currency conversion tracking, and proper monetary value handling across invoicing, payments, pricing, subscriptions, and financial transactions. The entity prevents common financial bugs such as adding amounts in different currencies, comparing incompatible monetary values, or losing currency context. It serves as the foundation for all financial operations in e-commerce, accounting, billing, and enterprise systems.
Properties
| Property | Type | Mode | Description | Required |
|---|---|---|---|---|
| amount | number | stored | The numeric amount value (supports decimals for fractional currency units) Example: | Required |
| currency | Currency | stored | The currency for this monetary amount (reference to Currency entity) | Required |
| formattedAmount | string | calculated | Formatted string representation with currency symbol (e.g., '$999.99', '€1.234,56') | Optional |
| amountInCents | number | calculated | Amount represented in smallest currency unit (cents, pence, etc.) to avoid floating-point precision issues | Optional |
Examples
Example 1
{
"@type": "MonetaryAmount",
"amount": 999.99,
"currency": {
"@type": "Currency",
"code": "USD",
"name": "US Dollar",
"symbol": "$"
}
}Example 2
{
"@type": "MonetaryAmount",
"amount": 1234.56,
"currency": {
"@type": "Currency",
"code": "EUR",
"name": "Euro",
"symbol": "€"
}
}Example 3
{
"@type": "MonetaryAmount",
"amount": 50000,
"currency": {
"@type": "Currency",
"code": "JPY",
"name": "Japanese Yen",
"symbol": "¥"
}
}Example 4
{
"@type": "MonetaryAmount",
"amount": 0,
"currency": {
"@type": "Currency",
"code": "USD",
"name": "US Dollar",
"symbol": "$"
}
}Example 5
{
"@type": "MonetaryAmount",
"amount": 49.99,
"currency": {
"@type": "Currency",
"code": "GBP",
"name": "British Pound Sterling",
"symbol": "£"
}
}