Conventions

Money

• Money is a JSON number, rounded half up (away from zero) at a fixed scale.
• Scales: amounts up to 4 decimal places, unit prices and unit costs up to 8, rates up to 6 and quantities up to 6.
• The currency is the account's, reported as currency by GET /organization. Documents do not repeat it.
• Parse money into a decimal type. Summing binary floating point numbers drifts by a cent sooner than you would expect.
• Cost and price fields need cost:read. Without it they read null, which means redacted, not zero.

Time

• Timestamps are ISO 8601 in UTC with a Z, such as 2026-09-10T14:30:00Z.
• Dates are YYYY-MM-DD with no time zone: an order date is a calendar date, not an instant.
• updated_since accepts an ISO 8601 timestamp. One without an offset is read as UTC.
• Date filters take YYYY-MM-DD. A malformed date is refused with 400.

Paging

• limit is 1 to 200, default 50. offset is 0 to 10,000. Values outside either range are refused with 400.
• pagination reports limit, offset, total and has_more.
• Use has_more to decide whether to fetch again. Computing it from offset and limit claims another page whenever total is an exact multiple of limit.
• Past the offset cap, page with updated_since or narrower filters. See Lots and incremental sync.

Sorting and filters

• sort takes a comma-separated list of field:direction, for example sort=name:desc,id:asc. Each operation's sort parameter lists the fields it accepts; any other field is refused with 400.
• id is always appended as the final sort key, and the response's order states the ordering that was applied. Offset paging over a non-unique ordering would let rows move between pages as you walk them.
• A filter that takes several values is repeated, for example status=OPEN&status=BACK_ORDER.
• Where a named filter would be ignored alongside search, the combination is refused with 400 rather than returning results that look filtered and are not.
• Query parameters an operation does not define are ignored, so a misspelled filter returns unfiltered results. Check pagination.total when a filter matters.

Nulls

null never means zero. Depending on the field, it means one of these, and the field's description in the reference says which:

PATCH

• Omit a field to leave it unchanged.
• Send null to clear a field that can be null. Sending null for a field that cannot be null is refused with 400.
• An address is written as a whole object: send it and every part is set from it, with an omitted part cleared.
• lines is replaced as a whole set. See Writing documents.

Identifiers

• Ids are positive integers. 0 or a negative id is refused with 400.
• Ids are scoped to your account. An id in the path that is not in your account is 404, whether or not it exists elsewhere, so no caller can probe another account.
• An id in a request body that is not in your account, and is not shared reference data, is refused with 400.
• NutraSoft's shared reference rows are marked is_global. You can read and reference them, but not change them: a write is 403 READ_ONLY.
• Codes such as customer_code are unique within your account; a duplicate is refused with 409.

Unknown fields

• Request bodies refuse fields they do not define, at every level, with 400. details names the field.
• Responses gain fields over time. Parse them permissively and ignore what you do not use.