# Keeta Menu Management API This API provides comprehensive menu management capabilities for Keeta platform integration, including menu synchronization, product status management, and real-time notifications. Version: v.1.0.0 ## Servers ``` https://open.mykeeta.com/api/open ``` ## Download OpenAPI description [Keeta Menu Management API](https://api-docs.mykeeta.com/_spec/apis/@standard/menu.yaml) ## OpenItemCode-Based ### Menu Synchronization - [POST /product/menu/sync](https://api-docs.mykeeta.com/apis/standard/menu/openitemcode-based/menusync.md): This endpoint enables menu synchronization for stores on Keeta. The system performs full-menu updates based on the provided data, implementing entity matching through the openItemCode field. App-level throttling: 1. The system identifies entities as follows: - : When matching openItemCode values exist in the store's current menu - : When no matching openItemCode values are found - : All existing entities with openItemCode values not present in the request A successful response only confirms successful submission of the synchronization task. Certain items may still fail during processing due to validation rules, requiring manual verification and resubmission by the caller. The endpoints supports standard HTTP/HTTPS (ports 80/443) external image URLs, which must comply with platform specifications regarding size, format, and accessibility. : | | | | --- | --- | | | - The openItemCode field is mandatory and must maintain uniqueness across entities- Each store cannot exceed 100 menu categories- Category names must be unique within a single store- Only one mandatory category is permitted per store- Categories become hidden when all contained products are delisted, and are repositioned when products become temporarily unavailable | | | - The openItemCode field is mandatory with entity-level uniqueness- Maximum 2,000 option groups per store- Maximum 10,000 options per store- Use the relatedSpuOpenItemCode to explicitly bind the ChoiceGroupSku to an existing SPU entity- Use the relatedSkuOpenItemCode to explicitly bind the ChoiceGroupSku to an 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.- When both relatedSkuOpenItemCode and relatedSpuOpenItemCode are declared, there will be a association check to ensure the SKU belongs to the declared SPU.- If both relatedSpuOpenItemCode and relatedSkuOpenItemCode are not specified, automatic binding occurs when the ChoiceGroupSku name matches a SPU name, enabling coordinated SPUs and ChoiceGroupSku status management(Note: If multiple SPUs share identical names, the system randomly selects one for binding, which may lead to unintended synchronization.)- External image URLs are supported in the pictureList field | | | - The openItemCode field is mandatory with entity-level uniqueness- Maximum 2,000 SPUs per store- Maximum 15 featured products per store- Tobacco/alcohol products must have corresponding attributes marked as "Yes"- External image URLs are supported in the pictureList field- Time-limited availability slots cannot overlap and are limited to 30 time periods- The shopCategoryOpenItemCodeList request should include the menu category openItemCode which exists in the specific store- The choiceGroupOpenItemCodeList request should include the choicegroup openItemCode which exists in the specific store | | | - Optional field that defaults to upload sequence when empty- Requires complete sorting data for all products across all categories when provided | ### Batch Update SPU Status - [POST /product/spustatus/batchupdatebycode](https://api-docs.mykeeta.com/apis/standard/menu/openitemcode-based/batchupdatespustatus.md): This endpoint allows the bulk updating of product statuses using their SPU OpenItemCode. App-level throttling: - The openItemCode field is mandatory with SPU entity-level uniqueness. - This endpoint supports partial successful updates when processing multiple SPUs in a single request. However, if the entire request contains fundamental structural errors the system will reject the complete batch with a fail response. - When the needLinkage parameter is set to 1, this endpoint facilitates the comprehensive synchronization of status changes not only for the specified SPUs but also for all associated ChoiceGroupSkus. This advanced functionality ensures cohesive inventory and product display management across related product options. - Each request cannot exceed 200 SPUs. ### Batch Update ChoiceGroupSku Status - [POST /product/choicegroupskustatus/batchupdatebycode](https://api-docs.mykeeta.com/apis/standard/menu/openitemcode-based/batchupdatechoicegroupskustatus.md): This endpoint allows users to efficiently modify the status of ChoicegroupSkus using their OpenItemCode. App-level throttling: - When developers call this endpoint to update the status of multiple options on the Keeta platform, it's essential to understand that the API processes each option independently. This can result in partial success, where some options are successfully updated while others encounter errors. ### Batch Bind OpenItemCode - [POST /product/mapping/batchupdatebyname](https://api-docs.mykeeta.com/apis/standard/menu/openitemcode-based/batchbindopenitemcode.md): The endpoints allows developers setting the OpenItemCode mapping relationship using store ID and product name. App-level throttling: - Existing partners that have already integrated via Keeta ID-based APIs must complete OpenItemCode binding for their existing products through this API before switching to OpenItemCode-based APIs, if they have previously created marketing campaigns on the Keeta platform. ## Webhooks ### Menu Synchronization Task Completion Notification - [POST menuSynchronizationTaskCompletionWebhook](https://api-docs.mykeeta.com/apis/standard/menu/webhooks/menusynchronizationtaskcompletionnotification.md): The API operates asynchronously. When Keeta's platform receives a synchronization request, it creates an internal task for processing. Upon task completion (success or failure), Keeta will notify developers via this webhook. 1202 ## KeetaID-Based ### Query ShopCategory list - [POST /product/shopcategory/list](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/queryshopcategorylist.md): Query the list of ShopCategory information in store. 50 QPS by appId dimension. ### Create a ShopCategory - [POST /product/shopcategory/create](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/createshopcategory.md): - Only for creating in-store ShopCategory. - The names of ShopCategory in a store are not allowed to be repeated. - The maximum "mandatory" ShopCategory number for each store is 1. - When there is no product available for sale under the ShopCategory (including products offshelf), the ShopCategory will not be displayed on our user APP. - The number of ShopCategory can not exceed 100. 10 QPS by appId dimension. ### Modify a ShopCategory - [POST /product/shopcategory/update](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updateshopcategory.md): - To update a ShopCategory information, will keep its original ID - Please ensure that each parameter is the value you want to update. 10 QPS by appId dimension. ### Delete ShopCategories(in batch) - [POST /product/shopcategory/batchdel](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/deleteshopcategories.md): 1. You can only delete ShopCategory that doesn't contain any product. 2. Please make sure the ShopCategory.id is in-store. 10 QPS by appId dimension. ### Adjust order of a ShopCategory - [POST /product/shopcategory/updatesequence](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updateshopcategorysequence.md): - Adjust one specific ShopCategory's order, the sequence need to be greater than 0 and less than the number of ShopCategories. 10 QPS by appId dimension. ### Adjust order of ShopCategories(in batch) - [POST /product/shopcategory/batchupdatesequence](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/batchupdateshopcategorysequence.md): - Adjust all ShopCategories' sequence in store. - Please make sure openShopCategorySequenceDTOList contains all shopCategory in store, otherwise the interface invoke will be rejected. 10 QPS by appId dimension. ### Query category attribute list - [POST /product/categoryproperty/list](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/querycategorypropertylist.md): 1. Get the category attribute list based on the final category ID, which is used for operations such as creating products. 2. Since there is no backend category field for this period, the categoryId can be fixed to -1. 50 QPS by appId dimension. ### Query products list - [POST /product/spu/list](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/queryproductslist.md): 1. Get all valid products in store. 50 QPS by appId dimension. ### Query a specific product - [POST /product/spu/detail](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/queryproductdetail.md): 1. Get a specific product info through ID, this is far more fast comparing to query products list. 100 QPS by appId dimension. ### Create products(in batch) - [POST /product/spu/batchcreate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/createproducts.md): 1. Product data that can be transmitted in one batch should not exceed 200. If there are more products, please create them in batches. 2. The interface supports partial synchronization success and partial synchronization failure. However, if there is a parameter format error, all will fail. 3. You can not create "ShopCategory" or "ChoiceGroup" through this interface, please make sure all the ShopCategory.id and ChoiceGroup.id are already exist in store. 4. Regarding the product image related Field, please use the "Image upload API" to upload the image to the KeeTa system first, than get the image URL and pass into the Picture.url field. 5. If it is a tobacco and alcohol product, please be sure to fill in the relevant attributes in the [Product Attributes] field to avoid regulatory issues. 6. If a Spu contains only one Sku, then the Sku.spec field is allowed to remain empty, otherwise the Sku.spec in a specific Spu need to be filled. 7. The Sku.price is required and supports up to two decimal places. 8. Spu.avaliableTime is required. 9. "Specialty" dish can not exceed 15 in a store. 10 QPS by appId dimension. ### Modify products(in batch) - [POST /product/spu/batchupdate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updateproducts.md): 1. Mostly like 3.3.3. 2. Through this interface, you can update Spu with its ID unchanged, . 3. As for Sku, if the Sku.id is filled, please make sure the Sku.id is belongs to this Spu. If Sku.id is not filled, we will treat it as a new one. 10 QPS by appId dimension. ### Modify the available and unavailable status(in batch) - [POST /product/spustatus/batchupdate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updateproductsstatus.md): 1. Product data that can be transmitted in one batch should not exceed 200. If there are more products, please create them in batches. 2. The interface supports partial synchronization success and partial synchronization failure. However, if there is a parameter format error, all will fail. 3. If there is no available product in a ShopCategory, the ShopCategory will disapear at user APP. 4. If needLinkage=1, this API will also modify the status linked to the ChoiceGroupSkus (the same name with Spu). But if the ChoiceGroupSku status violates the rule of ChoiceGroup, it wouldn't be modified. 10 QPS by appId dimension. ### Query conflict ChoiceGroup before unavailable (in batch) - [POST /product/spu/batchcheck](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/checkproductsconflict.md): 1. Query if there is any rule-violated ChoiceGroup when unavailable a Spu with linkage. 50 QPS by appId dimension. ### Delete products(in batch) - [POST /product/spu/batchdel](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/deleteproducts.md): 1. Product data that can be transmitted in one batch should not exceed 200. If there are more products, please delete them in batches. 2. The interface supports partial synchronization success and partial synchronization failure. However, if there is a parameter format error, all will fail. 3. If needLinkage=1, this API will also delete the linked ChoiceGroupSkus (the same name with Spu). But if the ChoiceGroupSku status violates the rule of ChoiceGroup, it wouldn't be modified. 50 QPS by appId dimension. ### Adjust order of a product(in a specific ShopCategory) - [POST /product/spu/updatesequence](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updateproductsequence.md): 1. Adjust a product's sequence in a specific ShopCategory. 2. 0 < sequence <= number of spus. 10 QPS by appId dimension. ### Adjust products order in a ShopCategory(in batch) - [POST /product/spu/batchupdatesequence](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/batchupdateproductsequence.md): 1. Adjust all products' sequence in a specific ShopCategory. 2. 0 < sequence <= number of spus. 3. Please make sure spuSequenceDTOList contains all Spu in the ShopCategory, otherwise it will fail. 10 QPS by appId dimension. ### Adjust products order in a Shop(in batch) - [POST /product/spu/batchupdateallsequence](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/batchupdateallproductsequence.md): 1. Mostly like 3.3.9 but support multiple ShopCategories. 10 QPS by appId dimension. ### Batch bind Spus picture(support other image urls) - [POST /product/spupicture/batchbind](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/batchbindproductpictures.md): 1. Noticed this is an Asynchronous API, if you want to subscribe error messages, please configure webhook with 「eventId=1201」; 2. Make sure all spuIds are belong to shopId; 3. Image requirements: 1. Image url can be access directly. We only support HTTP/HTTPS protocol for default port (80/tcp or 443/tcp), please don't use other ports; 2. Image size cannot exceed 5M, the minimum aspect of image is 600px * 450px; 3. In image url's header field, the Content-Type can only be "" or ""; 10 QPS by appId dimension. ### Query ChoiceGroup list - [POST /product/choicegroup/list](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/querychoicegrouplist.md): 1. Query all ChoiceGroups in store. 50 QPS by appId dimension. ### Create ChoiceGroups(in batch) - [POST /product/choicegroup/batchcreate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/createchoicegroups.md): 1. if the ChoiceGroupSku.name is the same as Spu.name, normally they will bound. 2. ChoiceGroup.maxNumber should greater than or equals to ChoiceGroup.minNumber and ChoiceGroup.maxNumber should greater than 0. 3. ChoiceGroupSku.price is required, status is required. 10 QPS by appId dimension. ### Modify ChoiceGroups(in batch) - [POST /product/choicegroup/batchupdate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updatechoicegroups.md): 1. Mostly like 3.4.2 but ChoiceGroup.id is required. 2. Please make sure the ChoiceGroup data object is complete. 10 QPS by appId dimension. ### Batch query which products are using these ChoiceGroups - [POST /product/choicegroup/listappliedspu](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/querychoicegroupappliedspu.md): 1. Query ChoiceGroup's applied products. 10 QPS by appId dimension. ### Delete ChoiceGroups(in batch) - [POST /product/choicegroup/batchdel](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/deletechoicegroups.md): 1. Batch delete ChoiceGroups and related ChoiceGroupSkus. 10 QPS by appId dimension. ### Modify ChoiceGroupSkus available/unavailable status(in batch) - [POST /product/choicegroupskustatus/batchupdate](https://api-docs.mykeeta.com/apis/standard/menu/keetaid-based/updatechoicegroupskustatus.md): 1. Notice that the available ChoiceGroupSkus should greater than or equals to minNumber. 10 QPS by appId dimension. ## Product Picture ### Image Upload - [POST /base/image/upload](https://api-docs.mykeeta.com/apis/standard/menu/product-picture/uploadimage.md): This endpoint allows merchants to upload images to the Keeta platform. The returned image URL can be used during menu synchronization. App-level throttling: - Different store locations may safely reuse the same image URL, and developers should avoid redundant uploads of identical images to prevent triggering rate limits. - Keeta exclusively accepts JPG and PNG file formats for image submissions. - Merchants should maintain consistent image dimensions across their catalog since significant variations in picture sizes may degrade display quality in consumer-facing applications, potentially hindering customers' ability to examine product details visually. - While the system enforces a hard , we strongly recommend keeping individual images to ensure optimal performance; uploads exceeding 5MB will automatically fail. - Although a 4:3 aspect ratio is recommended for ideal rendering, non-compliant images will be automatically cropped by the system, which may result in unintended scaling or distortion. - Minimum dimension requirements mandate images be at least wide and tall to maintain baseline quality standards. - Calls must utilize the multipart/form-data content type for parameter transmission. - Developers must exclude the imgData field from any signature calculation processes during authentication.