Skip to content

Decimal strings, dates and ids

How amounts, quantities, dates, ids and enum values are written, in both directions.

Version v1.1, updated

On this page

The API writes every amount and quantity as a decimal string, every time in UTC and every id as a UUID. You send them back the same way.

Decimal strings

A decimal string has an optional minus sign, digits, and optionally a dot with decimals: "12.50", "-3", "0.125". There is no thousands separator and no exponent.

A JSON number in a decimal field answers 422 validation_failed. Numbers can lose precision between two systems; a string keeps every digit.

Field family

Decimals

Example

Money: prices, totals, VAT amounts, payments

two

"64.50"

Unit prices of order and invoice lines

up to four

"3.2000"

Invoice line quantities

up to four

"20.0000"

Order line and stock quantities

up to three

"24.5"

VAT rates, in percent

two

"20.00"

A write refuses more decimals than its field allows, rather than rounding them. Responses always carry the full number of decimals of the field.

Dates and times

  • A time is ISO 8601 in UTC, with milliseconds and a Z: "2026-09-28T14:05:12.417Z".

  • A date alone is YYYY-MM-DD, such as paid_on or issue_date. It is the calendar day of the company, not a moment.

  • Filters such as updated_since accept any ISO 8601 time with an offset or Z.

Ids

Every record id is a UUID string, such as the id of a product; a stock level row has an id of its own. Treat every id as opaque text and never derive meaning from it.

Names and values

  • Field names are lowercase with underscores: customer_id, next_cursor.

  • Enum values are lowercase: goods, finished_product, draft.

  • null means "no value". A field the record does not have is still present, with null.

Related

  • responses
  • requests
  • invoices
  • glossary