Menu Export/Import

Import flow

Create Import Session

$ curl -X POST 'https://admin.digital-restaurant.gmo/api/admin/order-menu/import-create' -d 'shop=[shopId]' -H 'X-Auth-API-Key: [api-key-obtained]'
> { "objectId": "Object ID for processing", "url": "AWS URL for uploading"}

Upload File to S3

curl --data-binary "@path/to/archive" 'AWS URL for uploading'

Perform Import

curl -X POST 'https://admin.digital-restaurant.gmo/api/admin/order-menu/import-start' -d 'shop=[shopId]&deleteOld=[delete existing or not]&objectId=[import object id]' -H 'X-Auth-API-Key: [api-key-obtained]'

Then the upload will begin in background. You can use API below to get progress.

Query Import Progress

curl -X POST 'https://admin.digital-restaurant.gmo/api/admin/order-menu/import-state' -d 'shop=[shopId]&objectId=[import object id]' -H 'X-Auth-API-Key: [api-key-obtained]'

Model Definitions

Name	Type	Required	Description
id	UUID String	Yes	Unique ID for menu
menuTemplateId	UUID String	No	Foreign key of menu template
nameJa	String (255)	Yes	Name in Japanese
descJa	String (65536)	No	Description in Japanese, HTML formatted (see details)
shortDescJa	String (65536)	No	Short description in Japanese, better to have one line only
~~images~~	String (65536)	No	Images of menu, relative to archive root. JSON String Array format
image	String	No	Images of menu, relative to archive root. Can be an HTTPS URL. Multiple `<image/>` tags are allowed.
menuPrice	Integer	Yes	Price of a menu
taxIncludedFlg	Char	Yes	1 for tax incl. 0 otherwise
taxReliefApplicableFlg	Char	Yes	1 for 軽減税率対応商品
taxOverride	Integer	No	To override default tax calculation
taxReliefOverride	Integer	No	To override default tax calculation for 軽減税率対応商品
status	Enum (Menu.Status)	Yes	Status of menu, see Menu.Status
forTakeoutFlg	Char	Yes	1 for takeout menu
forDeliveryFlg	Char	Yes	1 for delivery menu
forCafeteriaFlg	Char	Yes	1 for food court menu
smaregiProductId	String (32)	No	ID for Smaregi product
maximumPerOrder	Integer	No	Maximum menu item per order limitation. 0 means no limitation
availableStartLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Menu will be disabled before this date/time (= PREPARING status)
availableEndLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Menu will be disabled after this date/time (= PREPARING status)
visibleStartLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Menu will be hidden before this date/time
visibleEndLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Menu will be hidden after this date/time
stock	Menu.StockRelationship	No	Stock linked to this menu
metadata	Menu.Metadata	No	Metadata for menu, ask sales for details
translation	Menu.Translation	No	Translations for menu, ask sales for details

Menu.Status

Value	Name	Description
10	DRAFT	Not visible to customers
15	PREPARING	Visible, but can't be selected for checkout
20	PUBLISHED	Visible to customers
90	DELETED	Marked for deletion, not visible to customers

Menu.StockRelationship

Name	Type	Description
id	UUID Attribute	Stock ID for this menu item

Menu.Metadata

Name	Type	Description
key	String Attribute	Metadata key
Content	Text Content(255)	Metadata value

Menu.Translation

Name	Type	Description
language	String Attribute	Language code
name	String(255)	Name in specified language
shortDesc	String	Short description in language
desc	String	Description in language

XML Example of Menus

Menu is stored in archive file as menus.xml

<Menus>
  <Item>
    <id>f8f32cd0-98aa-11ea-8e6f-0a58a9feac2a</id>
    <nameJa>カフェラテ</nameJa>
    <type>30</type>
    <descJa></descJa>
    <shortDescJa>グアテマラ産のエスプレッソにスチームミルク</shortDescJa>
    <!--
    Following field will be supported, but please use new format instead
    <images>["/images/course/268cc740-441e-11eb-87db-0a58a9feac2a.jpg"]</images>
    -->
    <!-- Suggested new format -->
    <image>/images/course/268cc740-441e-11eb-87db-0a58a9feac2a.jpg</image>
    <!-- Multiple items can be defined like this -->
    <image>/images/course/2a3d8668-013f-11ef-a08c-00155dff7986.jpg</image>
    <menuPrice>650</menuPrice>
    <menuPriceOriginal>0</menuPriceOriginal>
    <taxIncludedFlg>1</taxIncludedFlg>
    <taxReliefApplicableFlg>0</taxReliefApplicableFlg>
    <taxOverride>0</taxOverride>
    <taxReliefOverride>0</taxReliefOverride>
    <status>20</status>
    <forTakeoutFlg>1</forTakeoutFlg>
    <forDeliveryFlg>0</forDeliveryFlg>
    <forCafeteriaFlg>1</forCafeteriaFlg>
    <!-- One item only for an order -->
    <maximumPerOrder>1</maximumPerOrder>
    <!-- Stock linkages -->
    <stock id="bf133484-1348-11ef-a609-00155d5f6f50"/>
    <stock id="c424aa48-1348-11ef-aee9-00155d5f6f50"/>
    <!-- Metadata can be useful, please ask sales -->
    <metadata key="receipt_printer">kitchen</metadata>
    <metadata key="my_defined_key">My defined value</metadata>
    <translation language="en">
      <name>Café Latte</name>
      <shortDesc>Guatemalan espresso with steamed milk</shortDesc>
    </translation>
    <translation language="zh-CN">
      <name>咖啡拿铁</name>
      <shortDesc>危地马拉意式浓缩咖啡加入美味牛奶</shortDesc>
    </translation>
  </Item>
  <!-- more items... -->
</Menus>

Template

Name	Type	Description
id	UUID String	Unique ID for template
nameJa	String (255)	Name in Japanese

XML Example of Templates

Template is stored in archive file as templates.xml

<Templates>
  <Item>
    <id>f8881e50-7198-11eb-b689-0a58a9feac2a</id>
    <nameJa>すし</nameJa>
  </Item>
</Templates>

Variation

A variation (topping) is addition to a menu. For example extra Sliced pork on a bowl of Ramen (which costs extra money), or Wasabi preferences of a plate of sushi (free).

New format

A variation can be standalone, and normal menu can be used as variation, combined with VariationRelationship.

Name	Type	Required	Description
id	UUID String	Yes	Unique ID for variation
nameJa	String (255)	Yes	Name in Japanese
shortDescJa	String (65536)	No	Short description in Japanese, better to have one line only
~~images~~	String (65536)	No	Images of menu, relative to archive root. JSON String Array format
image	String	No	Images of menu, relative to archive root. Can be an HTTPS URL. Multiple `<image/>` tags are allowed.
menuPrice	Integer	Yes	Price of a menu
taxIncludedFlg	Char	No	1 for tax incl. 0 otherwise
taxReliefApplicableFlg	Char	No	1 for 軽減税率対応商品
taxOverride	Integer	No	To override default tax calculation
taxReliefOverride	Integer	No	To override default tax calculation for 軽減税率対応商品
smaregiProductId	String (32)	No	ID for Smaregi product
maximumPerOrder	Integer	No	Maximum menu item per order. (Not enabled yet)
availableStartLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Variation will be disabled before this date/time
availableEndLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Variation will be disabled after this date/time
visibleStartLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Variation will be hidden before this date/time
visibleEndLocalDateTime	Date(yyyy-MM-dd'T'HH:mm)	No	Variation will be hidden after this date/time
stock	Menu.StockRelationship	No	Stock linked to this menu
metadata	Menu.Metadata	No	Metadata for menu, ask sales for details
translation	Menu.Translation	No	Translations for menu, ask sales for details
~~variationParentId~~	~~UUID String~~	Not allowed
~~variationCategoryId~~	~~UUID String~~	Not allowed
~~sortOrder~~	~~Integer~~	Not allowed

Legacy format

A variation can belong to menu, or a template.

Name	Type	Description
id	UUID String	Unique ID for variation
nameJa	String (255)	Name in Japanese
menuPrice	Integer	Price of a menu
taxIncludedFlg	Char	1 for tax incl. 0 otherwise
taxReliefApplicableFlg	Char	1 for 軽減税率対応商品
taxOverride	Integer	To override default tax calculation
taxReliefOverride	Integer	To override default tax calculation for 軽減税率対応商品
smaregiProductId	String (32)	ID for Smaregi product
variationParentId	UUID String	Foreign key to Menu
variationCategoryId	UUID String	Foreign key to VariationCategory
sortOrder	Integer	Sort index in a category, starts from 0
maximumPerOrder	Integer	Maximum menu item per order limitation.

XML Example of Variations

Variations are stored in archive file as variations.xml

<Variations>
  <!-- variations under f8f32cd0-98aa-11ea-8e6f-0a58a9feac2a -->
  <Group key="f8f32cd0-98aa-11ea-8e6f-0a58a9feac2a">
    <Item>
      <id>a295d652-59ea-438c-a284-171ca8a2a7a5</id>
      <nameJa>クッキー</nameJa>
      <type>90</type>
      <!--
      Following field will be supported, but please use new format instead
      <images>["/images/course/268cc740-441e-11eb-87db-0a58a9feac2a.jpg"]</images>
      -->
      <!-- Suggested new format -->
      <image>/images/course/268cc740-441e-11eb-87db-0a58a9feac2a.jpg</image>
      <!-- Multiple items can be defined like this -->
      <image>/images/course/2a3d8668-013f-11ef-a08c-00155dff7986.jpg</image>
      <menuPrice>0</menuPrice>
      <taxIncludedFlg>1</taxIncludedFlg>
      <taxReliefApplicableFlg>0</taxReliefApplicableFlg>
      <taxOverride>0</taxOverride>
      <taxReliefOverride>0</taxReliefOverride>
      <!-- Following fields are not allowed in new format -->
      <variationParentId>f8f32cd0-98aa-11ea-8e6f-0a58a9feac2a</variationParentId>
      <variationCategoryId>7f2f143e-8dbc-490b-b156-440f042bbade</variationCategoryId>
      <sortOrder>0</sortOrder>
      <!-- Metadata can be useful, please ask sales -->
      <metadata key="receipt_printer">kitchen</metadata>
      <metadata key="my_defined_key">My defined value</metadata>
    </Item>
    <!-- more items... -->
  </Group>
  <!-- more groups... -->
</Variations>

VariationCategory

New format

In new menu format, Menu, Variation and VariationCategory, are connected by VariationRelationship object.

Name	Type	Description
id	UUID String	Unique ID for variation category
nameJa	String (30)	Name in Japanese
required	Boolean	If this category must be selected
exclusive	Boolean	If this category will be a single-selection dropdown
defaultChoiceNameJa	String (30)	Default name for dropdown when there's is no selection
showGallery	Boolean or null	`false` to show variations as dropdown or buttons only. `true` to show as horizontal list always. `null` to show as horizontal list if there are images in the variations.
~~sortOrder~~	~~Integer~~	Ignored.

Legacy format

Name	Type	Description
id	UUID String	Unique ID for variation category
nameJa	String (30)	Name in Japanese
required	Boolean	If this category must be selected
exclusive	Boolean	If this category will be a single-selection dropdown
defaultChoiceNameJa	String (30)	Default name for dropdown when there's is no selection
sortOrder	Integer	Sort index in a category, starts from 0

XML Example of VariationCategories

Variation categories is stored in archive file as variationCategories.xml

<VariationCategories>
  <Item>
    <id>a507d53e-57e5-40c3-a175-3333de305e03</id>
    <nameJa>1、ハンバーグ</nameJa>
    <required>false</required>
    <exclusive>false</exclusive>
    <!-- sortOrder field is not needed in new format -->
    <sortOrder>0</sortOrder>
    <showGallery/>
  </Item>
  <Item>
    <id>d1053262-45e9-4110-bd5f-f50acd7bb3bc</id>
    <nameJa>その他</nameJa>
    <required>true</required>
    <exclusive>true</exclusive>
    <defaultChoiceNameJa>なし</defaultChoiceNameJa>
    <sortOrder>1</sortOrder>
  </Item>
</VariationCategories>

VariationRelationship

In new menu format, Menu, Variation and VariationCategory, are connected by VariationRelationship object. By building relationship with items, you can now use normal menu items as topping for a menu. Duplicated variations or variation categories can also be eliminated.

Name	Type	Description
menu.key	UUID String	Foreign key to Menu
variation.key	UUID String	Foreign key to Menu, can be a variation or normal menu item
category.key	UUID String	Foreign key to VariationCategory
category.sortOrder	Integer	Index of variation categories in the menu, starts from 0
variation.sortOrder	Integer	Index of variation in the category, starts from 0

XML Example of VariationRelationships

Variation relationships is stored in archive file as variationRelationships.xml

<VariationRelationships>
  <Menu key="002c32f0-6a81-42f5-83ca-d7a4314bcb92">
    <Category key="ea818591-c15e-43e4-864d-0b81bb233fb7">
      <Variation key="e7a22ab8-5908-4018-8a87-7f5578645eec"/>
      <Variation key="4a8992dd-0534-4007-bc25-fc7863efa16f"/>
    </Category>
    <Category key="0f78c6ce-88d3-42a1-9574-fad1a86ef897">
      <Variation key="aa9a880d-709a-4001-8097-09429c0059c0"/>
    </Category>
  </Menu>
</VariationRelationships>

MenuCategory

Name	Type	Description
id	UUID String	Unique ID for menu category
nameJa	String (30)	Name in Japanese
sortOrder	Integer	Sort order for menu categories
profileId	UUID String	Foreign key to MenuCategoryProfile

XML Example of MenuCategories

Menu categories is stored in archive file as menuCategories.xml

<MenuCategories>
  <Item>
    <id>f49ad345-6eb6-4d4b-ade8-641f24a6d4a0</id>
    <nameJa>フード</nameJa>
    <sortOrder>0</sortOrder>
  </Item>
  <Item>
    <id>30a3392a-16d9-45fd-9f50-b648be0b8120</id>
    <nameJa>ドリンク</nameJa>
    <sortOrder>1</sortOrder>
  </Item>
  <Item>
    <id>2b9f0a3d-9fc2-4305-920f-708ae5ef9a4e</id>
    <nameJa>デザート</nameJa>
    <sortOrder>2</sortOrder>
  </Item>
</MenuCategories>

MenuCategoryProfile

A shop can have multiple menu category profiles, which can be used to show different menus to customers.

Default profile is always available.

When the slug is specified in the URL, only categories with the profile will be shown.

Name	Type	Description
id	UUID String	Unique ID for menu category
slug	String (64)	Slug (part of the URL) for profile. e.g. `special`
name	String (64)	Name of profile

XML Example of MenuCategoryProfiles

<MenuCategoryProfiles>
  <Profile>
    <id>cdb2c158-dec6-4e4b-9ded-0e2241ebf394</id>
    <slug>soup-packs</slug>
    <name>冷凍スープ/カレー</name>
  </Profile>
</MenuCategoryProfiles>

MenuCategoryRelationship

Name	Type	Description
categoryId	UUID String	Foreign key to category
menuId	UUID String	Foreign key to menu
sortOrder	Integer	Sort order for menu in the category

XML Example of MenuCategoryRelationships

Menu category relationships is stored in archive file as menuCategoryRelationships.xml

<MenuCategoryRelationships>
  <Group key="f49ad345-6eb6-4d4b-ade8-641f24a6d4a0">
    <Item>
      <categoryId>f49ad345-6eb6-4d4b-ade8-641f24a6d4a0</categoryId>
      <menuId>2455fa50-9a5a-11ea-8e6f-0a58a9feac2a</menuId>
      <sortOrder>0</sortOrder>
    </Item>
    <Item>
      <categoryId>f49ad345-6eb6-4d4b-ade8-641f24a6d4a0</categoryId>
      <menuId>d3184ad0-4427-11eb-8c6f-0a58a9feac2a</menuId>
      <sortOrder>1</sortOrder>
    </Item>
    <Item>
      <categoryId>f49ad345-6eb6-4d4b-ade8-641f24a6d4a0</categoryId>
      <menuId>c428c940-4428-11eb-86ca-0a58a9feac2a</menuId>
      <sortOrder>2</sortOrder>
    </Item>
    <!-- more items... -->
  </Group>
  <!-- more groups... -->
</MenuCategoryRelationships>

Stock

Item to manage availability of linked menu items.

Name	Type	Required	Description
id	UUID String	Yes	Unique ID for stock
name	String (50)	Yes	Name of stock item
available	Boolean	No	Linked menu will not be able to add to cart if false
visible	Boolean	No	Linked menu will not visible to customers if false
memo	String(200)	No	Memo for stock item
group	String(50)	No	Group name for stock item. Stock with same group name will be placed into the same section

XML Example of Stocks

Stocks are stored in archive file as stocks.xml

<Stocks>
  <Stock>
    <id>c424aa48-1348-11ef-aee9-00155d5f6f50</id>
    <name>エスプレッソ</name>
    <available>true</available>
    <visible>true</visible>
    <group>飲み物</group>
  </Stock>
  <Stock>
    <id>bf133484-1348-11ef-a609-00155d5f6f50</id>
    <name>牛乳</name>
    <available>true</available>
    <visible>true</visible>
    <memo>おいしい牛乳</memo>
    <group>飲み物</group>
  </Stock>
</Stocks>

Images

Images are stored in images/course related to archive root. Please don't upload huge images, for better experience when user visits the shop page.

Caveats

Migrated Menus

If a shop has their menus migrated to new format, then during import, if deleteOld is not set to true, import file with old menu format will be rejected, and vise versa.

If deleteOld is specified, then the menu data will be fully replaced (old data will be all deleted).

Import flow​

Create Import Session​

Upload File to S3​

Perform Import​

Query Import Progress​

Model Definitions​

Menu​

Menu.Status​

Menu.StockRelationship​

Menu.Metadata​

Menu.Translation​

XML Example of Menus​

Template​

XML Example of Templates​

Variation​

New format​

Legacy format​

XML Example of Variations​

VariationCategory​

New format​

Legacy format​

XML Example of VariationCategories​

VariationRelationship​

XML Example of VariationRelationships​

MenuCategory​

XML Example of MenuCategories​

MenuCategoryProfile​

XML Example of MenuCategoryProfiles​

MenuCategoryRelationship​

XML Example of MenuCategoryRelationships​

Stock​

XML Example of Stocks​

Images​

Caveats​

Migrated Menus​

Import flow

Create Import Session

Upload File to S3

Perform Import

Query Import Progress

Model Definitions

Menu

Menu.Status

Menu.StockRelationship

Menu.Metadata

Menu.Translation

XML Example of Menus

Template

XML Example of Templates

Variation

New format

Legacy format

XML Example of Variations

VariationCategory

New format

Legacy format

XML Example of VariationCategories

VariationRelationship

XML Example of VariationRelationships

MenuCategory

XML Example of MenuCategories

MenuCategoryProfile

XML Example of MenuCategoryProfiles

MenuCategoryRelationship

XML Example of MenuCategoryRelationships

Stock

XML Example of Stocks

Images

Caveats

Migrated Menus