Time, numbers and money
Objective
Section titled “Objective”Read this page before writing any code that parses a Shelf Cloud response.
Requirements
Section titled “Requirements”- None
Instructions
Section titled “Instructions”All timestamps are UTC, ISO 8601 extended, with a Z suffix.
Services mirroring an AWS API emit millisecond precision, because their AWS counterparts do and clients parse accordingly:
2026-09-03T14:22:07.000ZServices with no AWS counterpart emit second precision unless a field documents otherwise:
2026-09-03T14:22:07ZNo local times, no offsets, no epoch seconds in any customer-facing field. A field carrying a date without a time is documented as a date.
Durations are integers of seconds, and the field name says so.
Our clock is in the Date header of every response so that a client can detect
its own drift before signatures begin failing.
Numbers
Section titled “Numbers”Integers are integers. Nothing that counts is returned as a string.
Sizes are in bytes unless the field name carries another unit, and where another
unit is used the name carries it: SizeGiB, MemoryMiB, ThroughputMbps.
Binary units are binary — a GiB is 1024³. Decimal units are decimal — a Mbps is 10⁶ bits per second. The two are never mixed inside one field, and the field name always says which is meant.
Monetary amounts are an integer of minor units with an explicit currency:
{ "Amount": 1980, "Currency": "EUR" }That is €19.80.
Never a float, never a decimal string. Floating point cannot represent decimal money exactly, and a rounding error in an invoice is not a rounding error, it is a dispute.
OPEN (Michael): the billing currency, and whether more than one is offered. A currency is per-account and permanent, so it must be settled before any account is created.
A rate needs more precision than a price, because a per-second rate is a small fraction of a minor unit:
{ "Amount": 550, "Scale": 6, "Currency": "EUR", "Unit": "instance-second" }Scale is the number of decimal places beyond the minor unit that Amount
carries. The example is 0.000550 cents per instance-second.
OPEN (Michael): the rounding rule — at which step rounding occurs, and in which direction. Rounding per record, per line and per invoice give different totals, and the difference is visible to any customer who checks.
Net and gross
Section titled “Net and gross”Amounts are stated net of tax unless a field name says otherwise. Tax is a separate line, and the gross total is stated separately.
| Field | Meaning |
|---|---|
AmountNet | Before tax |
TaxAmount | Tax on that base |
AmountGross | Net plus tax |
An amount with no statement of whether it includes tax is not a reconcilable figure, and for a provider selling across EU borders it is a legal exposure rather than an inconvenience.
OPEN (Michael): the tax model — rate determination, place of supply, the reverse charge for VAT-registered business customers in other member states, and where the VAT identification number is captured.
Percentages and ratios
Section titled “Percentages and ratios”Decimals with a documented scale, or basis points where a field says so. Never a string with a percent sign.
Null and absent
Section titled “Null and absent”A field that is absent is absent. A field present and null means the value is known to be nothing. Empty strings are never used to mean absent.
Go further
Section titled “Go further”- Metering events
- Billing API data types