Time and monetary values

Our APIs use consistent formats for representing values of certain data types.

Time

Use RFC 3339 for time values. We store and return times in UTC timezone.

We will accept times in any time zone, though, as required by RFC 3339; you do need to specify the offset properly. We will convert any incoming time values to UTC for you.

Example: 1990-12-31T23:59:60Z.

Date

Some values like birthdays and statistical days are pure dates, represented as YYYY-MM-DD strings. These are generally interpreted as corresponding to day boundaries in the shop time zone.

Birthdays may lack a year, in which case it is encoded as 0000 (0000-MM-DD).

Monetary

In API responses, monetary values are encoded as decimal strings with exactly 6 digits of precision, e.g. "42.990000".

On input, we accept two representations:

• same format as responses — a decimal string representation of the value (you can use any precision you like);
• an integer representing the value multiplied by 1_000_000 (e.g. $1 = 1000000, $0.01 = 10000).

Note that we do not accept straight floating-point values. We strongly recommend against using floating-point numbers to deal with monetary values.

Internally, we use fixed-point decimal values with 6 digits of precision when storing and processing monetary values. (Another way to explain it is that we store monetary values as 64-bit integers, premultiplied by 1_000_000.)

Monetary with Currency

Some monetary values include currency. We encode these as a 2-element [amount, "currency"] array.

Permyriads

Percentages are specified as integer permyriads, aka 1/100s of a percent. (In other words, percentages are represented by decimal fixed-point numbers with 2 digits of precision, encoded as integers.)

Bubbleflake

These are internal Bubblehouse identifiers assigned to all objects it deals with. These identifiers use a format similar to Snowflake; we're calling it Bubbleflake.

In the API, they are represented by 16-character hex strings (e.g. "197a332e1f02002e"). You should treat these as opaque strings. (You are allowed to parse them into unsigned 64-bit integers if you'd like, e.g. for efficiency reasons on your side. But be sure to format these into 16-character lowercase hex strings with leading zeros before passing them back to Bubblehouse.)

Within a given shop, Bubbleflakes are unique and monotonically increasing, i.e. later objects get larger Bubbleflake values. (The values are increasing whether you treat them as strings or as integers, because the strings have a fixed length.)

Optional properties

Response properties marked as optional may be either omitted or set to null by Bubblehouse. You need to support both cases.