Clarification on implementing Square’s multi-level category hierarchy

Questions
1

Hi Square Team,

I’m looking for some clarification regarding how multi-level category hierarchies should be interpreted and implemented when consuming the Square Catalog API.

System Context

We have built a multi-merchant restaurant platform integrated with Square.

Each restaurant/merchant connects their Square account to our platform using OAuth. Once connected, our system:

  • Pulls the merchant’s catalog/menu from Square.
  • Imports categories, items, item variations, modifier lists, and modifiers.
  • Displays the menu on our customer-facing application.
  • Allows customers to browse categories and select items.
  • Creates orders through Square.
  • Processes payments using Square Terminal.

We are currently working on correctly mapping Square’s category hierarchy into our own menu/navigation structure.

From the Square documentation/capability information, we understand that categories support:

“Multi-level hierarchy — organizational only.”

We would appreciate clarification on the following points.

1. What exactly does “organizational only” mean?

For example, if Square contains:

Food
   └── Burgers
        └── Chicken Burgers

should we interpret these simply as navigation/grouping levels, rather than levels that require any customer selection?

In other words, does the category hierarchy have any effect on ordering rules, or is it purely used to organize where items appear?

2. Can items exist directly at every category level?

For example:

Food
│
├── Item A
│
└── Burgers
    │
    ├── Item B
    │
    └── Chicken Burgers
        │
        ├── Item C
        └── Item D

Is this a valid Square structure?

If the customer opens Food, should our application show:

  • Item A
  • Burgers as a child category

and then, after opening Burgers:

  • Item B
  • Chicken Burgers as a child category

Is this the expected way to interpret the hierarchy?

3. Are categories ever “required” or “optional”?

For modifier lists, we understand that Square provides selection rules such as minimum and maximum selected modifiers.

Do similar rules exist for categories?

For example, if there are three category levels:

Food
→ Burgers
→ Chicken Burgers

is there ever a requirement that the customer must navigate/select something from each level?

Or should categories always be treated as optional navigation, with selection requirements applying only to variations/modifier lists?

4. Is there a maximum supported category nesting depth?

Should we expect a fixed maximum such as:

Level 1
→ Level 2
→ Level 3

or can category nesting continue beyond three levels?

We want to make sure we do not hard-code a three-level structure if Square supports arbitrary/deeper nesting.

Our intended implementation would be recursive:

Category
   ├── Items
   └── Child Categories
        ├── Items
        └── Child Categories
             └── ...

Is this the recommended approach?

5. Can one item belong to multiple categories?

For example:

Spicy Chicken Burger

Categories:
- Chicken Burgers
- Spicy Items
- Best Sellers

If this is supported, should we expect the item’s category collection to contain all of these category IDs and allow the same item to appear in multiple places in our menu?

6. Parent vs. child category item inheritance

If an item is assigned directly to:

Chicken Burgers

and Chicken Burgers belongs to:

Food
→ Burgers
→ Chicken Burgers

should that item also be considered part of the parent categories automatically?

Or should we only consider an item directly associated with the category IDs explicitly returned on the item?

For example, should:

Chicken Burger
categories = [CHICKEN_BURGERS]

appear only when viewing CHICKEN_BURGERS, or should our application also surface it automatically under BURGERS and FOOD?

Our main goal is to accurately reproduce the merchant’s Square menu structure while avoiding assumptions that could cause items to disappear, appear under the wrong category, or force customers through unnecessary category levels.

Any guidance on the recommended interpretation of category hierarchy for a third-party restaurant integration would be greatly appreciated.

3

Hello!

  1. Categories are purely organizational (like a file folder), items need to be in at least one menu category in square for restaurants but can technically exist in just the ordering channel if created via the API.
    I will note that there are regular categories and menu categories that typically surface the same path at least at the top level. I would build your structure following the ids returned by the categories themselves instead of just listing all categories and showing them.
  2. Your diagram is correct, they can be at any level.
  3. There are no min/max selection rules on categories, but they exist purely for browsing and reporting purposes.
  4. Your recursive approach is the right way to go. Use is_top_level, parent_category, and root_category fields to reconstruct the tree, and optionally path_to_root (returned when include_category_path_to_root=true) for convenience.
  5. An item can appear in Chicken Burgers, Spicy Items, and Best Sellers simultaneously. Show it in all of them. Note the distinction: categories (array) controls where the item appears in navigation, while reporting_category (single) is used for analytics/loyalty.
  6. If an item’s categories array contains only CHICKEN_BURGERS, it appears only under Chicken Burgers. It does not automatically bubble up to Burgers or Food. Show items only under the category IDs explicitly listed in their categories field. If a merchant wants an item visible at multiple levels, they assign it to each category explicitly.