Field Naming & Data Structure Guidelines

This document describes our internal API field and structure guidelines, which we share publicly so you can better understand how and why we design our API the way we do.Field Naming & Data Structure Guidelines

1. Field Naming Rules

UIDs

• All fields that reference a technical unique identifier must end with Uid.

  Example: productUid, orderUid

Quantities

• All fields that reference a stock or quantity must start with quantity.

  Example: quantityOrdered, quantityInStock, quantityReserved

Entity References

• Fields that refer to another entity must always use the same field name as in the original entity.

  Example: If an order line references a product, the field must be called productUid.

2. Field Types

• Uid — Required unique identifier (string)

• OptionalUid — Optional unique identifier (string)

  • Use Uid when the reference is required.

  • Use OptionalUid when the reference is optional or can be unset.

3. Clearing Fields

• Text fields — Clear by sending an empty string "".

• Uid fields (OptionalUid) — Clear by sending an empty string "".

• Date fields — Clear by sending null.

4. Lists & Search Responses

All list and search endpoints must return:

• items — The array of results.

• paging — Pagination information.

5. Pagination Rules

The paging object must include:

Field	Description
totalCount	Total number of elements in the result set.
pageNumber	Current page number (defaults to 1 if not provided).
pageSize	Number of items requested per page.

Example:

A search with 27 results and pageSize = 24:

{
  "totalCount": 27,
  "pageNumber": 1,
  "pageSize": 24
}

To check if there are more pages:

• If items.length < pageSize, this is the last page.

This format keeps your internal rules crystal-clear for your own developers, but also makes it easy for external devs to understand how to structure their requests and interpret responses.