Field naming & data structure

How fields are named, how references work, and how to clear a value.

These are the conventions the API is built on. They are published because knowing them lets you predict a field name instead of looking it up.

Naming rules

Identifiers end in Uid. Any field referencing a technical unique identifier is named for the entity plus Uid — productUid, orderUid, warehouseUid. They are strings, not integers.

Quantities start with quantity. Any stock or count field leads with it — quantityOrdered, quantityInStock, quantityReserved.

References reuse the target's name. When one entity points at another, the field keeps the name it has on the original entity. An order line referencing a product calls it productUid, never itemUid or articleUid. If you know the entity, you know the field.

Required and optional references

Type	Meaning
Uid	Required reference. Always present.
OptionalUid	Optional reference. May be absent, and may be cleared.

Clearing a field

This one is not guessable, and getting it wrong silently leaves the old value in place.

Field type	Clear it by sending
Text	"" (empty string)
OptionalUid	"" (empty string)
Date	null

Sending null to a text field is not the same as sending "", and will not clear it.

List and search responses

Every list and search endpoint returns the same two keys:

{
  "items": [ ... ],
  "paging": {
    "totalCount": 27,
    "pageNumber": 1,
    "pageSize": 24
  }
}

• items — the results.

• paging — where you are: totalCount, pageNumber, pageSize.

There is no cursor and no next link. You are on the last page when items.length < pageSize.

Forward compatibility

Fields are added over time without a version bump. Parse the fields you use and ignore the rest — a client that rejects unknown fields will break on a release that was meant to be additive.