Manage Menus

Applies to: Catalog API

Learn how to manage menus with the Catalog API and catalog categories.

This guide walks you through syncing menus using Square's Catalog API, for example, to display a seller's offerings in your kiosk, mobile application, or online ordering site. You'll also learn how to create root menu categories and organize menus for different services, such as breakfast and lunch.

When a seller creates a menu through the Square Dashboard, the system automatically creates catalog categories with a CategoryType of MENU_CATEGORY. These categories are used to organize items in the seller's menu and are distinct from regular catalog categories.

Key points about menu categories:

• Automatically created when sellers build menus in the Square Dashboard
• Have a category_type of MENU_CATEGORY
• Used specifically for menu organization
• Like regular categories, can have parent-child relationships
• Can be used across different sales channels

• A Square account with Square Free, Plus, and Premium subscribers with advanced restaurant capabilities added.
• A Square account with full service, quick service, or bar mode enabled in the Square Point of Sale application.
• Your Square application credentials.
• Authorization to use the Square Catalog API.

When integrating with your application or other external systems, you need an efficient way to sync menu data. This section covers both initial sync and incremental updates.

CatalogCategory objects handle location visibility differently than other Catalog objects. Instead of direct location assignment, they use channels as an abstraction layer:

• Channel objects act as the bridge between menu categories and locations
• Each Location has a corresponding channel (identified by reference.type = "LOCATION")
• Menu categories declare visibility by listing channel IDs in their channels array

To synchronize menus for a specific location:

1. Get the channel ID for your target location
2. Filter menu categories to include only those referencing that channel
3. Sync only these filtered categories to ensure location-specific accuracy

See Channels API - Menu visibility for more information about mapping channels to locations.

In the following examples, a restaurant creates a breakfast menu and lunch menu. Each menu has a root category and child categories. The breakfast beverages menu has a submenu for coffee drinks.

To perform a complete menu sync with an external service (such as a delivery platform), you need three specific API calls to get all menu-related catalog objects in the correct hierarchy.

Get all of the descendants of the root categories.

{
  "object": {
      "type": "CATEGORY",
      "id": "ZTVXYFS633S6GSLMHVP5O5IG",
      "updated_at": "2025-06-02T22:04:56.684Z",
      "created_at": "2025-06-02T22:04:56.898Z",
      "version": 1748901896684,
      "is_deleted": false,
      "present_at_all_locations": true,
      "category_data": {
        "name": "Coffee-drinks",
        "image_ids": [
          "BAXRGSINXCHS7RW4ZMQSHGGL"
        ],
        "category_type": "MENU_CATEGORY",
        "parent_category": {
          "id": "H5P6BRQKWKL6BDZKIS4FGPSM",
          "ordinal": -2251731094208512
        },
        "is_top_level": false,
        "channels": [
          "CH_IT55vdjtd81xkZvF68NXQqPO54qnOXkyQRkiBQlQuYC",
          "CH_leic5ZC8kuuyAVAIQUlxuEG72EYFNBoxFCz5574e9945o"
        ],
        "online_visibility": false,
        "root_category": "3H3ADZMYJU6U27JYO2PZFANQ"
      }
    }
}

To complete the menu, your application needs to get the items, variations, any modifier lists, images, and other resources related to the items shown on the menus. You can get all this information with a single API call. Note that you need to include the "include_related_objects": true query parameter.

To keep your application's menu data current with the seller's Square catalog, implement a periodic sync strategy to capture various types of menu changes.

• Item modifications (price, description, or images)
• Menu structure changes (new categories or item reorganization)
• Item availability updates
• New item additions or removals

To learn about tracking availability updates, see Monitor Sold-out Item Variations or Modifiers.

You can efficiently track these changes using the updated_at timestamp in the SearchCatalogObjects endpoint:

After retrieving any changes to the menu structure, you want to get any changes to menu items and related types.

When working with the Catalog API, it's important to understand the distinction between menu categories and regular categories:

• Menu categories

  • Created through the Square Dashboard's menu builder.
  • Have category_type = "MENU_CATEGORY".
  • Used specifically for menu organization.
  • Like regular categories, support parent-child relationships.
  • Can be synchronized across channels.

• Regular categories

  • Created through the Catalog API.
  • Have category_type = "REGULAR_CATEGORY".
  • Used for general item organization.
  • Might appear as duplicates of menu categories.

First, use the Catalog API to retrieve existing menu categories.

When creating categories for different locations, ensure you:

• Set the correct category_type.
• Establish proper parent-child relationships.
• Use consistent naming across locations.

The following shows an example for a delivery service menu category:

When creating subcategories, always reference the parent menu category.

When working with menu categories, it's important to understand that the structure you see in the Square Dashboard is represented by MENU_CATEGORY types in the Catalog API. The following example shows how different menu structures might look:

Restaurant Menu (MENU_CATEGORY)
├── Beverages
│   ├── Non-Alcoholic
│   │   ├── Iced Tea (Small/Large)
│   │   ├── Soft Drinks (Regular/Large)
│   │   └── Coffee (Small/Large)
│   ├── Beer
│   │   ├── Draft (Domestic/Craft)
│   │   └── Bottled (Domestic/Imported)
│   └── Wine
│       ├── Red (Glass/Bottle)
│       └── White (Glass/Bottle)
├── Appetizers
│   ├── Mozzarella Sticks
│   ├── Wings (6pc/12pc)
│   └── Nachos
└── Entrees
    ├── Sandwiches
    │   ├── Club
    │   └── BLT
    └── Salads
        ├── Caesar
        └── Garden

Delivery Menu (MENU_CATEGORY)
├── Beverages
│   ├── Iced Tea (Small/Large)
│   ├── Soft Drinks (Regular/Large)
│   └── Coffee (Small/Large)
├── Appetizers
│   ├── Mozzarella Sticks
│   ├── Wings (6pc/12pc)
│   └── Nachos
└── Entrees
    ├── Sandwiches
    │   ├── Club
    │   └── BLT
    └── Salads
        ├── Caesar
        └── Garden

• Cause: Items appearing in both menu and regular categories.
• Solution: Filter specifically for MENU_CATEGORY types.
• Prevention: Use proper category type filtering in API calls.

• Cause: Looking at the wrong category type.
• Solution: Check both menu and regular category associations.
• Prevention: Implement proper category type checking.

• Cause: Mixing menu and regular categories.
• Solution: Maintain proper parent-child relationships.
• Prevention: Validate category types and relationships.

1. Category filtering

   Search catalog objects

   cURL

2. Relationship maintenance

   • Track both menu and regular category IDs.
   • Update all relevant category associations.
   • Maintain a proper hierarchy.

3. Data validation

   • Verify category types before updates.
   • Check parent-child relationships.
   • Validate item associations.

1. Verify data

   • Compare item counts.
   • Validate category structures.
   • Check modifier associations.

2. Monitor performance

   • Track sync times.
   • Monitor API usage.
   • Optimize query patterns.

3. Setup alerts

   • Configure sync failure notifications.
   • Monitor for pricing discrepancies.
   • Alert when structure changes occur.