Data Formats

Field types at a glance

{
  "id": "8f3c9d2e-1a4b-4c7d-9e0f-2b6a1c3d4e5f",
  "order_number": "SO-0001",
  "status": "PENDING",
  "total": "60.00",
  "quantity": "5",
  "order_datetime": "2025-05-04T04:40:21.817570Z",
  "delivered_datetime": null
}

The API uses consistent types across every endpoint. Build your integration against these rules, not against the shape of any single response.

Type	Format
IDs	UUID strings, e.g. `"8f3c9d2e-1a4b-4c7d-9e0f-2b6a1c3d4e5f"`. Treat them as opaque — do not parse or assume ordering.
Numbers	All quantities, prices, and monetary amounts are strings, e.g. `"60.00"`, `"5"`. This preserves exact decimal precision that JSON floats cannot. Parse them with a decimal library, never a float. A few fields still return JSON numbers today; we will make them strings in the next API version, so parse defensively.
Datetimes	UTC, ISO-8601 with microseconds and a `Z` suffix: `YYYY-MM-DDTHH:MM:SS.MSZ`. Datetime fields end in `_datetime` (e.g. `order_datetime`, `delivered_datetime`).
Enums	Stable uppercase string tokens, e.g. `"PENDING"`, `"COMPLETED"`. A few enums are not yet uppercase; we will normalize them in the next API version. New values may be added over time — handle unknown tokens gracefully.
Booleans	JSON `true` / `false`.
Null	An absent or unset value is `null`, not omitted. Optional fields are always present in the response.

Conventions

Money and quantities are strings. "total": "60.00" is a string, not the number 60.0. Never round-trip these through a float — use a decimal type in your language.
Unknown fields may appear at any time. We add fields to responses without notice and consider that non-breaking. Your parser must ignore fields it does not recognize.
Custom fields appear under custom_data as a list of objects, each with the field's id, name, and value.
IDs are opaque. Their format may change; match on equality only.

ConventionsCopy Anchor Link

On this page

Conventions