🧾 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:

The user needs to make a selection from each category of choice (one Size AND one Color).

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:

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.

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 Options	Group 2 Options	Group 3 Options	Total 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"
}

🧾 Variants & Combinations

The Challenge: Multiple Choices#

Our Solution: Two Key Structures#

How Combinations are Calculated#

Modifier Groups (Add-ons)#

Comprehensive Examples#

Example 1: Burger with ONE Variant Group (Patty Size) + Modifiers#