📐 Data Layout

This section defines the common patterns and conventions you will see across all the data structure detailed below.

Understanding these standards will make the specific data structures easier to use.

Identifiers (IDs)

All primary identifiers for data records (e.g., for Merchants, Items, Customers) follow a consistent format: a human-readable prefix followed by a unique, URL-safe string.

Format: prefix_uniqueId

Examples: mer_AbCd1234, item_a1b2c3d4, ord_x1y2z3w4

System Timestamp

To ensure data versioning and enable reliable recovery from synchronization failures, all major data records include a timestamp of their last modification.

Field: updated_at

Purpose: The timestamp of the most recent change to the record.

Format: All timestamps are provided in ISO 8601 format and are in the UTC timezone (e.g., 2025-10-16T14:05:00Z).

Data Relationships

Our data models are interconnected. You will see fields ending in _id throughout the documentation. These fields contain the unique identifiers of related data models, creating a clear and logical link between them. For example, a Product record will contain an item_id to link it to the master Item record in our global catalog.

Identifiers (IDs)#

System Timestamp#

Data Relationships#

Identifiers (IDs)

System Timestamp

Data Relationships