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

🧾 Variants & Combinations

Handling products that come in different options (like size, color, or style) requires a structured approach. This page explains how we model these variations using variant_groups and variant_combinations.

The Challenge: Multiple Choices#
Imagine a simple T-Shirt. It might come in different Sizes (Small, Medium, Large) and different Colors (Red, Blue). A customer doesn't just buy a "T-Shirt"; they buy a specific combination, like a "Medium Blue T-Shirt".
A simple list of options isn't enough because:
1.
The user needs to make a selection from each category of choice (one Size AND one Color).
2.
Each specific combination (Medium + Blue) is a unique item with its own final price and, crucially, its own inventory level tracked by a unique SKU (Stock Keeping Unit).

Our Solution: Two Key Structures#
We use two arrays within the main Product object:
1.
variant_groups Array:
Purpose: Defines the categories of choice and the available options within each. Think of these as the questions the user must answer (e.g., "What size?", "What color?").
Structure: A list of groups. Each group has:
name: The name of the choice category (e.g., "Size").
selection_type: Always "single" for variants (user must pick one).
variants: A list of the available options. Each option has:
id: A unique ID for this specific option (e.g., v_size_m).
name: The display name (e.g., "Medium").
price_adjustment: How much this option adds (or subtracts) from the product's base price.
Key Point: This section defines potential choices, not the final purchasable items. No final SKUs here.
2.
variant_combinations Array:
Purpose: Explicitly lists every valid, purchasable combination of variants. This is the source of truth for final SKUs and prices.
Structure: A list of combination objects. Each object represents one specific final item (e.g., "Medium Blue T-Shirt") and contains:
sku: The final, unique, mandatory SKU for this specific combination (e.g., TSHIRT-M-BLU). This is the SKU used for inventory tracking.
price: The final calculated price for this specific combination (Base Price + all relevant price_adjustment values).
options: An array specifying exactly which variant id was chosen from each variant_group to make this combination.

How Combinations are Calculated#
The total number of entries in the variant_combinations array is the product of the number of options in each variant_group.
Group 1 OptionsGroup 2 OptionsGroup 3 OptionsTotal Combinations
3 (e.g., S, M, L)--3
3 (e.g., S, M, L)2 (e.g., Red, Blue)-3 x 2 = 6
3 (Size)2 (Fabric)3 (Collar)3 x 2 x 3 = 18

Modifier Groups (Add-ons)#
Optional customizations (like "Extra Cheese" or "Gift Wrap") are handled separately in the modifier_groups array. These are typically added after a specific variant_combination is chosen and usually add to the price. They do not typically affect the base SKU. See the main Products page for details.

Comprehensive Examples#

Example 1: Burger with ONE Variant Group (Patty Size) + Modifiers#
Base Product: Classic Burger, Base Price: 32.00 SAR (for Single), Base SKU: RBH-CLASSIC-BASE
Variant Group: "Patty Size" (Single=0.00, Double=+10.00)
Resulting Combinations: 2 (Single, Double)
{
  "id": "prod_rbh_classic_burger",
  "item_id": "item_rbh_classic_burger",
  "merchant_id": "mer_riyadh_burger_house",
  "price": 32.00,
  "currency": "SAR",
  "sku": "RBH-CLASSIC-BASE",

  "variant_groups": [
    {
      "id": "vargrp_burger_patty", "name": "Patty Size", "selection_type": "single",
      "variants": [
        { "id": "v_patty_single", "name": "Single Patty", "price_adjustment": 0.00 },
        { "id": "v_patty_double", "name": "Double Patty", "price_adjustment": 10.00 }
      ]
    }
  ],

  "variant_combinations": [
    {
      "sku": "RBH-CLASSIC-S",
      "price": 32.00,
      "options": [{ "group_id": "vargrp_burger_patty", "variant_id": "v_patty_single" }]
    },
    {
      "sku": "RBH-CLASSIC-D",
      "price": 42.00,
      "options": [{ "group_id": "vargrp_burger_patty", "variant_id": "v_patty_double" }]
    }
  ],

  "modifier_groups": [
    {
      "id": "modgrp_burger_toppings", "name": "Add Toppings", "selection_type": "multiple",
      "modifiers": [
        { "id": "mod_cheese", "name": "Extra Cheese", "price": 3.00 },
        { "id": "mod_jalapenos", "name": "JalapeΓ±os", "price": 2.00 }
      ]
    }
  ],
  "updated_at": "2025-10-18T16:00:00Z"
}
Example 2: Product with MULTIPLE Variant Groups (Shirt)#
Base Product: Basic Shirt, Base Price: 80.00 SAR (for Small, White), Base SKU: SHIRT-BASIC
Variant Group 1: "Size" (Small=+0, Medium=+5, Large=+10) - 3 options
Variant Group 2: "Color" (White=+0, Red=+0, Blue=+2) - 3 options
Resulting Combinations: 3 x 3 = 9
{
  "id": "prod_shirt_custom",
  "item_id": "item_basic_shirt",
  "merchant_id": "mer_fashion_store",
  "price": 80.00,
  "currency": "SAR",
  "sku": "SHIRT-BASIC",

  "variant_groups": [
    {
      "id": "vargrp_shirt_size", "name": "Size", "selection_type": "single",
      "variants": [
        { "id": "v_size_s", "name": "Small", "price_adjustment": 0.00 },
        { "id": "v_size_m", "name": "Medium", "price_adjustment": 5.00 },
        { "id": "v_size_l", "name": "Large", "price_adjustment": 10.00 }
      ]
    },
    {
      "id": "vargrp_shirt_color", "name": "Color", "selection_type": "single",
      "variants": [
        { "id": "v_color_white", "name": "White", "price_adjustment": 0.00 },
        { "id": "v_color_red", "name": "Red", "price_adjustment": 0.00 },
        { "id": "v_color_blue", "name": "Blue", "price_adjustment": 2.00 }
      ]
    }
  ],

  "variant_combinations": [
    {
      "sku": "SHIRT-S-WHT",
      "price": 80.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_s" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_white" }
      ]
    },
    {
      "sku": "SHIRT-S-RD",
      "price": 80.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_s" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_red" }
      ]
    },
    {
      "sku": "SHIRT-S-BLU",
      "price": 82.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_s" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_blue" }
      ]
    },
    {
      "sku": "SHIRT-M-WHT",
      "price": 85.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_m" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_white" }
      ]
    },
    {
      "sku": "SHIRT-M-RD",
      "price": 85.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_m" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_red" }
      ]
    },
    {
      "sku": "SHIRT-M-BLU",
      "price": 87.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_m" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_blue" }
      ]
    },
    {
      "sku": "SHIRT-L-WHT",
      "price": 90.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_l" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_white" }
      ]
    },
    {
      "sku": "SHIRT-L-RD",
      "price": 90.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_l" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_red" }
      ]
    },
    {
      "sku": "SHIRT-L-BLU",
      "price": 92.00,
      "options": [
        { "group_id": "vargrp_shirt_size", "variant_id": "v_size_l" },
        { "group_id": "vargrp_shirt_color", "variant_id": "v_color_blue" }
      ]
    }
  ],

  "modifier_groups": [],
  "updated_at": "2025-10-18T15:00:00Z"
}

Previous
🧾 Orders
Next
πŸ”Œ API Requirements
Built with