Sanal AI
  1. Data Structures
Sanal AI
  • Introduction
    • ๐Ÿš€ Sanal AI - Encore Data
    • ๐Ÿ› ๏ธ Getting Started
    • ๐Ÿค The Approach / Model
  • Data Structures
    • ๐Ÿ“ Data Layout
    • ๐Ÿช Merchants
    • ๐Ÿ“‚ Categories
    • ๐Ÿท๏ธ Items
    • ๐Ÿ›’ Products
    • ๐Ÿ“ฆ Inventory
    • ๐Ÿ‘ค Customers
    • ๐Ÿงพ Orders
    • ๐Ÿงพ Variants & Combinations
  • API Requirements
    • ๐Ÿ”Œ API Requirements
    • API: `syncMerchants`
    • API: `syncCategories`
    • API: `syncItems`
    • API: `syncProducts`
    • API: `syncInventory`
    • API: `syncCustomers`
    • API: `syncOrders`
  1. Data Structures

๐Ÿช Merchants

This object represents a single partner selling on the Sanal AI platform.

Fields#

NameTypeDescription
idstringThe unique identifier for the merchant (e.g., mer_AbCd1234).
namestringThe public display name (e.g., "Riyadh Burger House").
legal_namestringThe official registered business name.
is_activebooleanMaster switch (true/false) to show or hide the merchant entirely. See "Understanding Availability".
statusstringReal-time operational status within scheduled hours (e.g., accepting_orders, busy, temporarily_closed). See "Understanding Availability".
addressobjectStructured physical address (street, city, country using ISO 3166-1 alpha-2).
locationobjectPrecise geographic coordinates (latitude, longitude).
merchant_typestringHigh-level category (e.g., restaurant, retail_store, grocery).
tagsarrayList of descriptive keywords for search (e.g., ["burgers", "halal"]).
operating_hoursarrayList defining scheduled opening hours per day (day_of_week, open_time, close_time in 24h local). See "Understanding Availability".
updated_atstringTimestamp of the last modification (ISO 8601 UTC).

Understanding Merchant Availability#

The AI needs to determine if a merchant can fulfill an order right now. This depends on the interaction of three fields, checked in this order:
1.
is_active (boolean): If false, the merchant is completely unavailable and should never be shown (e.g., permanently closed, suspended, onboarding incomplete).
2.
operating_hours (array): Check if the current time falls within the scheduled open_time and close_time for the current day_of_week in the merchant's local timezone. If outside these hours, they are closed.
3.
status (string): If within operating_hours, this field provides real-time overrides.
"accepting_orders": Open and ready.
"busy": Open, but may experience delays.
"temporarily_closed": Within scheduled hours but currently unable to take orders (e.g., kitchen issue, cleaning). Treat as closed.

Sample JSON#

Restaurant Example#
{
  "id": "mer_AbCd1234",
  "name": "Riyadh Burger House",
  "legal_name": "Riyadh Foods Company LLC",
  "is_active": true,
  "status": "accepting_orders",
  "address": { "street": "789 King Fahd Road", "city": "Riyadh", "country": "SA" },
  "location": { "latitude": 24.7136, "longitude": 46.6753 },
  "merchant_type": "restaurant",
  "tags": ["burgers", "fast_food", "halal", "family_friendly"],
  "operating_hours": [
    { "day_of_week": "saturday", "open_time": "12:00", "close_time": "01:00" },
    { "day_of_week": "sunday", "open_time": "12:00", "close_time": "01:00" }
  ],
  "updated_at": "2025-10-15T16:30:00Z"
}
Grocery Store Example#
{
  "id": "mer_TmRydh01",
  "name": "Tamimi Markets - Olaya",
  "legal_name": "Tamimi Markets Company",
  "is_active": true,
  "status": "accepting_orders",
  "address": { "street": "123 Olaya Street", "city": "Riyadh", "country": "SA" },
  "location": { "latitude": 24.7000, "longitude": 46.6833 },
  "merchant_type": "grocery",
  "tags": ["supermarket", "fresh_produce", "bakery", "imported_goods"],
  "operating_hours": [
    { "day_of_week": "saturday", "open_time": "08:00", "close_time": "23:59" },
    { "day_of_week": "sunday", "open_time": "08:00", "close_time": "23:59" }
  ],
  "updated_at": "2025-10-16T09:00:00Z"
}

Previous
๐Ÿ“ Data Layout
Next
๐Ÿ“‚ Categories
Built with