IDs, money and time

How identifiers, amounts and instants are written

Three conventions hold on every object, so a field of each kind is read the same way everywhere.

IDs

An id is a prefix naming the object and 22 letters and digits. It never changes. An id sent to the wrong endpoint - a venue id to /customers - is a 404, never somebody else's record.

Object	Prefix
venue	`ven_`
customer	`cus_`
booking	`bkg_`
order	`ord_`
activity	`act_`
package	`pkg_`
event	`evt_`
event date	`evd_`
ticket	`tkt_`
gift card	`gft_`
tag	`tag_`
list	`lst_`
api key	`key_`

The handles people read - a booking number, an order number, a slug - are fields, and some lists filter by them.

Money

Every amount is an integer number of cents, never a decimal or a string, with a lowercase ISO 4217 currency. 4500 with aud is $45.00. On an order, amount_paid is already net of refunds.

Time

An instant - created_at, scheduled_at - is UTC, ISO 8601, ending in Z.
Where a venue's own calendar matters, the object also carries local_date (yyyy-MM-dd), local_time (HH:mm, 24-hour) and the venue's IANA timezone, such as Australia/Sydney.
A booking at 10am in Perth is local_time 10:00 in Australia/Perth, whatever time zone your server runs in.

Versioning Idempotency