# Menu API Integration Guide

## 1. Keeta Menu Model

The Keeta menu system is primarily composed of the following entities:

- **Shop**
A physical or virtual store location managed by a merchant. Menus are organized and maintained at this individual store level.
- **ShopCategory**
Menu sections created by merchants to group products (Merchants fully control these groupings). Menu categories form a tree structure where products must be placed in final-level subcategories, with current support for only one level of category nesting.
- **SPU (Standard Product Unit)**
The base product definition customers can order. Contains: Product name and description, core attributes, category assignment.
- **SKU (Stock Keeping Unit)**
The smallest inventory management unit representing specific variants of a product. Contains specifications and pricing details.
- **ChoiceGroup**
An entity that groups product customization options (commonly called "toppings" or "add-ons" in the industry). It serves as a container for related modifiers that can be applied to multiple SKUs.
- **ChoiceGroupSku**

  Represents an individual customization option within a ChoiceGroup. Identically named options can have different prices when used in different groups.

  Under the ChoiceGroupSku entity, use the relatedSkuOpenItemCode field to explicitly bind the current ChoiceGroupSku to another existing SKU entity. When the ChoiceGroupSku binds to a SKU, it will use the bounded SKU's ChoiceGroups to form a multi-layer ChoiceGroup structure (this feature is only available through OpenItemCode-Based Menu Syncrhonization API).


menuIntegrationGuide1.png
## 2. Entity ID

Keeta supports menu synchronization interfaces for two ID types: 'entity IDs generated by Keeta' (abbreviated as Keeta ID) and 'entity IDs generated by the third-party system' (abbreviated as OpenItemCode).

### 2.1 Keeta ID-Based Product-Level API

**Keeta ID** refers to a **unified identification system** where Keeta generates and manages unique identifiers for core menu entities. These IDs are platform-wide unique keys used across all Keeta services. Here are the IDs related to Keeta Menu Model:

- shopId: Unique store identifier
- shopCategoryId: Menu grouping identifier
- spuId: SPU ID
- skuId: SKU ID
- choiceGroupId: Modifier group identifier
- choiceGroupSkuId: Modifier identifier
- propertyId: Attribute type identifier
- propertyValueId: Attribute value identifier


### 2.2 OpenItemCode-Based Store-Level API

**OpenItemCode** refers to external identifier managed by a **third-party system** that maps to Keeta's entity IDs.

**Key Rules**:

1. The third-parties generate and control these codes.
2. Keeta performs **no validation** on format or logic.
3. Must ensure the uniqueness per entity type, immutability after binding and consistency across operations of the OpenItemCodes.


**Keeta supports binding of OpenItemCode to the following entity identifiers:**

| **Keeta ID** | **Entity Type** |
|  --- | --- |
| shopCategoryId | Menu Category |
| spuId | Standard Product Unit |
| skuId | Product Variant |
| choiceGroupId | Option Group |
| choiceGroupSkuId | Individual Option |


## 3. API Selection Matrix

Choose the OpenItemCode API for rapid store-level synchronization with minimal complexity, or select the Keeta ID API for granular product-level control requiring ID mapping management.

| **Criteria** | **OpenItemCode API** | **Keeta ID API** |
|  --- | --- | --- |
| Implementation Speed | Fast | Relatively slow |
| Maintenance Overhead | Low (Keeta manages IDs) | High (You manage mapping) |
| Control Granularity | Store-level | Product-level |
| Endpoint Count | 3 core endpoints | 25+ endpoints |
| Best Use Case | Simple menus, quick launch | Complex menus, real-time ops |
| ID System Visibility | None required | Full access |


## 4. Menu Specifications

### 4.1 Supported Languages

Keeta menus support the following language codes:

| **Language Code** | **Language** |
|  --- | --- |
| zh-HK | Traditional Chinese |
| en | English |
| ar | Arabic |


### 4.2 Supported Currencies

Keeta currently supports the following currencies for menu implementation (following ISO 4217):

| **Currency Code** | **Currency Name** |
|  --- | --- |
| HKD | Hong Kong Dollar |
| SAR | Saudi Riyal |
| KWD | Kuwaiti Dinar |
| AED | UAE Dirham |
| QAR | Qatari Riyal |
| OMR | Omani Rial |
| BHD | Bahraini Dinar |
| BRL | Brazilian Real |


**Note**: For monetary amounts, while three decimal places are supported in certain regions, the majority of regions accommodate up to two decimal places. Developers should ensure that amount values are transmitted in accordance with market-specific requirements to prevent data transmission errors due to incorrect formatting

### 4.3 Nutritional Information

Certain markets mandate nutritional information declaration for **SKU and ChoiceGroupSku entities**. Nutritional data must be provided as key-value pairs (KV format) where keys are predefined nutrient identifiers (exact strings), and values are positive integers representing nutrient amounts.

| Nutrition | Unit |
|  --- | --- |
| Calories | kcal |
| Protein | g |
| Total Fat | g |
| Saturated Fat | g |
| Trans Fat | g |
| Cholesterol | mg |
| Carbohydrates | g |
| Fiber | g |
| Total Sugars | g |
| Added Sugar | g |
| Salt | g |
| Sodium | mg |



```javascript
// Example
{
  "nutritionalInfo": {
    "calories_kcal": 100,
    "protein_g": 100,
    "totalFat_g": 100,
    "saturatedFat_g": 100,
    "transFat_g": 100,
    "cholesterol_mg": 100,
    "carbohydrates_g": 100,
    "fiber_g": 100,
    "totalSugar_g": 100,
    "addedSugar_g": 100,
    "salt_g": 100,
    "sodium_mg": 100
  }
}
```

### 4.4 Allergen Information Specification

**Definition**:

Certain markets (notably Saudi Arabia under SFDA regulations) require allergen declarations for **SKU and ChoiceGroupSku entities**. Allergen information must be provided as a **string enum list** with the following characteristics:

| Type | Enum value |
|  --- | --- |
| Celery and its products | Celery |
| Sulfite | Sulfite |
| Milk and milk products | Milk |
| Nuts and their products | Nuts |
| Peanuts and their products | Peanuts |
| Fish and fish products | Fish |
| Grains | Grains |
| Soybeans and their products | Soybeans |
| Lupins and their products | Lupins |
| Molluscs and their products | Molluscs |
| Sesame seeds and their products | Sesame seeds |
| Mustard and its products | Mustard |
| Eggs and their products | Eggs |
| Crustaceans and their products | Crustaceans |



```javascript
// Example
{
  "allergens": ["Celery", "Sulfite", "Milk", "Nuts", "Peanuts", "Fish", "Grains", "Soybeans", "Lupins", "Molluscs", "Sesame seeds", "Mustard", "Eggs", "Crustaceans"]
}
```

### 4.5 Caffeine

Regulatory requirements in certain markets mandate the inclusion of caffeine information on SKU and ChoiceGroupSKU entities.
This data must be structured in key-value format.

| Value | Date Type | Value constraints | Unit |
|  --- | --- | --- | --- |
| Caffeine | BigDecimal | Must be a non-negative number (≥0)Limited to 13 significant digits maximumDecimal precision cannot exceed 2 places | mg |



```javascript
// Example
{
  "caffeine": "123.99"
}
```

## 5. Menu Creation Workflow

For integrations using Keeta ID-based APIs follow this sequence to handle hierarchical dependencies and ensure data integrity:

1. Create menu categories and obtain menu category IDs
2. Create choice groups and obtain choice group IDs
3. Upload images and obtain image URLs
4. Create SPUs and associate them with the correct menu categories, choice groups, and image URLs
5. Adjust the display order of each entity according to requirements


menuIntegrationGuide2