Money and dates

Two conventions that cause more integration bugs than anything else on this list.

Money is an integer, in minor units

{ "amountMinor": 42000, "currencyCode": "USD" }

That is 420.00 USD. Every monetary value on the API is an integer count of the currency's minor unit, alongside a sibling ISO 4217 code.

Never a float. A nightly rate of 420.00 stored as a double is not reliably 420.00, and a total assembled from several of them drifts. The bug surfaces as a one-cent discrepancy in somebody's payout months later, which is an expensive way to learn it.

The minor unit is not always two decimal places. JPY has none, so 42000 JPY is 42,000 yen. Use a currency library rather than dividing by 100.

Do not compute totals

Where Haven returns a total, use it. Do not assemble one from the line items.

Totals involve fees, taxes, discounts and rounding rules that vary by jurisdiction and by host configuration, and reimplementing them means maintaining a second version of Haven's pricing logic that will diverge. If a total you need is missing from a payload, that is worth reporting.

Two date formats, and they are not interchangeable

Stay dates are YYYY-MM-DD. Check-in, check-out, a blocked night, the date a price override applies to.

{ "startDate": "2026-09-14", "endDate": "2026-09-17" }

These are calendar dates in the listing's own timezone, not instants. A guest checking in on 14 September checks in on 14 September regardless of where your server runs. Sending 2026-09-14T00:00:00Z for a listing in Los Angeles shifts the stay a day west, and the booking lands on the wrong night.

Parse these as dates. In JavaScript, new Date('2026-09-14') gives you a UTC midnight instant that will format as 13 September in any timezone behind UTC. Keep the string, or use a date type that has no time component.

Timestamps are ISO 8601 with an offset, and mean an actual moment: when a reservation was created, when a message was sent.

{ "createdAt": "2026-08-31T14:02:11.000Z" }

Parse these as instants. Convert for display; store them as sent.

Ranges are half-open

startDate is inclusive, endDate is exclusive. A stay from 2026-09-14 to 2026-09-17 occupies the nights of the 14th, 15th and 16th, and the guest leaves on the morning of the 17th. That night is available.

Half-open ranges are what make adjacent bookings expressible without an off-by-one: one stay ending on the 17th and another beginning on the 17th are consistent, not a double booking.

Timezones

Every listing carries an IANA timezone. Use it for anything a human at the property would recognize as a date: which night is blocked, whether a check-in is today.

Do not use the host account's timezone for property-level reasoning. A host in Denver can own listings in Lisbon.