Menu API Integration Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude

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).

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:

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.

4. Menu Specifications

4.1 Supported Languages

Keeta menus support the following language codes:

4.2 Supported Currencies

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

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.

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

// 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.

// 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